Códigos de error de REST para la API de HTTP v1
Las respuestas de errores de HTTP para la API de HTTP v1 contienen un código de error, un mensaje de error y un estado de error. También pueden contener un array details con más detalles
sobre el error.
A continuación, se muestran dos ejemplos de respuestas de error:
Ejemplo 1: Respuesta de error de una solicitud a la API de HTTP v1 con un valor no válido en un mensaje de datos
{
"error": {
"code": 400,
"message": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "message.data[0].value",
"description": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12"
}
]
}
]
}
}
Ejemplo 2: Respuesta de error de una solicitud a la API de HTTP v1 con un token de registro no válido
{
"error": {
"code": 400,
"message": "The registration token is not a valid FCM registration token",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
"errorCode": "INVALID_ARGUMENT"
}
]
}
}
Ten en cuenta que ambos mensajes tienen el mismo código y el mismo estado, pero el array de detalles contiene valores de tipos diferentes. El primer ejemplo tiene el tipo type.googleapis.com/google.rpc.BadRequest, que indica un error en los valores de la solicitud. El segundo ejemplo con el tipo type.googleapis.com/google.firebase.fcm.v1.FcmError tiene un error específico de FCM.
En muchos errores, la matriz de detalles contiene la información que necesitarás para depurar y encontrar una solución.
En la siguiente tabla, se enumeran los códigos de error de la API de REST v1 de FCM y sus descripciones.
| Código de error | Descripción y pasos de resolución |
|---|---|
UNSPECIFIED_ERROR No hay más información disponible sobre este error. |
Ninguno |
INVALID_ARGUMENT (código de error de HTTP = 400) Los parámetros de la solicitud no eran válidos. Se muestra una extensión de tipo google.rpc.BadRequest para especificar qué campo no era válido. |
Entre las posibles causas, se incluyen un registro no válido, un nombre de paquete no válido, un mensaje demasiado grande, una clave de datos no válida, un TTL no válido y otros parámetros no válidos. Registro no válido: Verifica el formato del token de registro que pasaste al servidor. Asegúrate de que coincida con el token de registro que la app cliente recibe cuando se registra en FCM. No lo trunques el token ni agregues caracteres adicionales. Nombre de paquete no válido: Asegúrate de que el mensaje se haya dirigido a un token de registro cuyo nombre de paquete coincida con el valor pasado en la solicitud. Mensaje demasiado grande: Verifica que el tamaño total de los datos de carga útil incluidos en un mensaje no supere los límites de FCM: 4,096 bytes para la mayoría de los mensajes, o 2,048 bytes para los mensajes a temas. Esto incluye las claves y los valores. Clave de datos no válida: Verifica que los datos de carga útil no contengan una clave (como from, gcm o cualquier valor con el prefijo de Google) que FCM usa de forma interna. Ten en cuenta que FCM también usa algunas palabras (como collapse_key), pero se permiten en la carga útil. En este caso, el valor de FCM anulará el valor de la carga útil. TTL no válido: Verifica que el valor que se usa en ttl sea un número entero que represente la duración en segundos entre 0 y 2,419,200 (4 semanas). Parámetros no válidos: Verifica que los parámetros proporcionados tengan el nombre y el tipo correctos. |
UNREGISTERED (código de error de HTTP = 404) Se canceló el registro de la instancia de la app en FCM. Por lo general, esto significa que el token utilizado ya no es válido y se debe usar uno nuevo. |
Este error puede deberse a tokens de registro faltantes o no registrados. Falta el registro: Si el objetivo del mensaje es un valor token, verifica que la solicitud contenga un token de registro.No registrado: Un token de registro existente puede dejar de ser válido en diversas situaciones, como las siguientes: - Si la app cliente deja de estar registrada en FCM. - Si se cancela el registro de la app cliente de forma automática, lo cual puede ocurrir si el usuario desinstala la aplicación. Por ejemplo, en iOS esto sucede si el servicio de comentarios de APNs informó que los tokens de APNs no son válidos. - Si caduca el token de registro (por ejemplo, porque Google decidió actualizar estos tokens o porque caducó el token de APNs para los dispositivos iOS). - Si la app cliente se actualiza, pero la nueva versión no está configurada para recibir mensajes. En todos estos casos, debes quitar este token de registro del servidor de apps y dejar de utilizarlo para enviar mensajes. |
SENDER_ID_MISMATCH (código de error de HTTP = 403) El ID de remitente autenticado es diferente del ID de remitente del token de registro. |
Un token de registro está asociado con un determinado grupo de emisores. Cuando una app cliente se registra para FCM, debe especificar qué remitentes tienen autorización para enviar mensajes. Debes utilizar el ID de uno de esos remitentes cuando envíes mensajes a la app cliente. Si cambias a otro diferente, los tokens de registro existentes no funcionarán. |
QUOTA_EXCEEDED (código de error de HTTP = 429): Se superó el límite de envío para el destino del mensaje. Se muestra una extensión de tipo google.rpc.QuotaFailure para especificar qué cuota se superó. |
Este error puede deberse a que se excedió la cuota de frecuencia de mensajes, la cuota de frecuencia de mensajes de dispositivos o la cuota de frecuencia de mensajes de temas. Tasa de mensajes excedida: La frecuencia de envío de mensajes es demasiado alta. Debes reducir la tasa general a la que envías mensajes. Usa la retirada exponencial con un retraso inicial mínimo de 1 minuto para reintentar los mensajes rechazados. Tasa de mensajes de dispositivos excedida: La tasa de mensajes a un dispositivo determinado es demasiado alta. Consulta el límite de frecuencia de mensajes a un solo dispositivo. Reduce la cantidad de mensajes enviados a este dispositivo y usa la retirada exponencial para volver a intentar el envío. Tasa de mensajes de temas excedida: La tasa de mensajes a suscriptores de un tema particular es demasiado alta. Reduce la cantidad de mensajes enviados a este tema y usa la retirada exponencial con una demora inicial mínima de 1 minuto para volver a intentar el envío. |
UNAVAILABLE (código de error de HTTP = 503). El servidor está sobrecargado. |
El servidor no pudo procesar la solicitud a tiempo. Vuelve a intentar con la misma solicitud, pero haz lo siguiente: - Respeta el encabezado Reintento posterior si se incluye en la respuesta del servidor de conexiones de FCM. - Implementa la retirada exponencial en el mecanismo de reintento. (p. ej., si esperaste un segundo antes del primer intento, espera al menos dos segundos antes del próximo, luego, 4 segundos y así sucesivamente). Si envías varios mensajes, considera aplicar Jitter. Para obtener más información, consulta Cómo manejar los reintentos o revisa el panel de estado de FCM para identificar si hay interrupciones del servicio en curso que afecten a FCM. Los remitentes que causen problemas corren el riesgo de ser incluidos en una lista de bloqueo. |
INTERNAL (código de error de HTTP = 500) Se produjo un error interno desconocido. |
Se produjo un error en el servidor mientras se intentaba procesar la solicitud. Puedes volver a intentar con la misma solicitud. Para ello, sigue las sugerencias incluidas en Cómo manejar los reintentos o consulta el panel de estado de FCM para identificar si hay interrupciones del servicio en curso que afecten a FCM. Si el error persiste, comunícate con el equipo de asistencia de Firebase. |
THIRD_PARTY_AUTH_ERROR (código de error de HTTP = 401): El certificado de APNs o la clave de autorización de notificaciones push web no eran válidos o faltaban. |
No se pudo enviar un mensaje destinado a un dispositivo iOS o a un registro push web. Verifica la validez de tus credenciales de desarrollo y producción. |
Códigos de error del SDK de Admin
En la siguiente tabla, se muestra una lista de los códigos de error de la API de Admin de FCM de Firebase y sus descripciones, además de los pasos recomendados para resolverlos.
| Código de error | Descripción y pasos de resolución |
|---|---|
messaging/invalid-argument |
Se proporcionó un argumento no válido al método de FCM. El mensaje de error debe incluir información adicional. |
messaging/invalid-recipient |
El destinatario del mensaje no es válido. El mensaje de error debe incluir información adicional. |
messaging/invalid-payload |
Se proporcionó un objeto de carga útil del mensaje no válido. El mensaje de error debe incluir información adicional. |
messaging/invalid-data-payload-key |
La carga útil del mensaje de datos contiene una clave no válida. Consulta la documentación de referencia de DataMessagePayload para ver las claves restringidas.
|
messaging/payload-size-limit-exceeded |
La carga útil del mensaje que se proporcionó supera el límite de tamaño de FCM. El límite es de 4,096 bytes para la mayoría de los mensajes. Para los mensajes enviados a los temas, el límite es de 2,048 bytes. El tamaño total de la carga útil incluye las claves y los valores. |
messaging/invalid-options |
Se proporcionó un objeto de opciones de mensaje no válido. El mensaje de error debe incluir información adicional. |
messaging/invalid-registration-token |
Se proporcionó un token de registro no válido. Asegúrate de que coincida con el token de registro que la app cliente recibe cuando se registra en FCM. No lo trunques ni le agregues caracteres adicionales. |
messaging/registration-token-not-registered |
El token de registro que se proporcionó no está registrado. Se puede cancelar el registro de un token válido por distintos motivos, como los siguientes:
|
messaging/invalid-package-name |
El mensaje se dirigió a un token de registro cuyo nombre de paquete no coincide con la opción restrictedPackageName proporcionada. |
messaging/message-rate-exceeded |
La tasa de mensajes a un objetivo específico es demasiado alta. Reduce la cantidad de mensajes que se envían a este dispositivo o tema, y no intentes reenviar mensajes de inmediato al mismo destino. |
messaging/device-message-rate-exceeded |
La tasa de mensajes a un dispositivo específico es demasiado alta. Reduce la cantidad de mensajes que se envían a este dispositivo y no intentes volver a enviarle mensajes de inmediato. |
messaging/topics-message-rate-exceeded |
La tasa de mensajes a suscriptores de un tema particular es demasiado alta. Reduce la cantidad de mensajes enviados a ese tema y no intentes volver a enviar mensajes de inmediato. |
messaging/too-many-topics |
Un token de registro se suscribió a la cantidad máxima de temas y no se puede suscribir a ningún otro. |
messaging/invalid-apns-credentials |
No se pudo enviar un mensaje destinado a un dispositivo Apple, ya que el certificado SSL de APNs obligatorio venció o no se subió. Verifica la validez de los certificados de programación y producción. |
messaging/mismatched-credential |
La credencial que se usó para autenticar este SDK no tiene permiso para enviar mensajes al dispositivo que corresponde al token de registro proporcionado. Asegúrate de que el token de registro y la credencial pertenecen al mismo proyecto de Firebase. Consulta Agrega Firebase a tu app para ver la documentación sobre cómo autenticar los Firebase Admin SDK. |
messaging/authentication-error |
El SDK no pudo autenticarse en los servidores de FCM. Asegúrate de autenticar Firebase Admin SDK con una credencial que tenga los permisos adecuados para enviar mensajes de FCM. Consulta Agrega Firebase a tu app para ver la documentación sobre cómo autenticar los Firebase Admin SDK. |
messaging/server-unavailable |
El servidor de FCM no pudo procesar la solicitud a tiempo. Vuelve a intentarlo
con la misma solicitud, pero esta vez haz lo siguiente:
|
messaging/internal-error |
Se produjo un error en el servidor de FCM mientras se intentaba procesar la
solicitud. Puedes volver a intentar con la misma solicitud; para ello, sigue los requisitos que se
enumeran en la fila messaging/server-unavailable anterior. Si el
error persiste, informa el problema a nuestro canal de asistencia
de informe de errores.
|
messaging/unknown-error |
Se obtuvo como resultado un error desconocido del servidor. Consulta la respuesta del servidor sin procesar en el mensaje de error para ver más detalles. Si recibes este error, informa el mensaje de error completo a nuestro canal de asistencia de informes de errores. |