Códigos de erro REST para a API HTTP v1
As respostas de erro HTTP para a API HTTP v1 contêm um código do erro, uma mensagem de erro e o status do erro. Eles também podem conter uma matriz details com mais detalhes sobre o erro.
Veja dois exemplos de respostas de erro:
Exemplo 1: resposta de erro de uma solicitação de API HTTP v1 com um valor inválido em uma mensagem de dados
{
"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"
}
]
}
]
}
}
Exemplo 2: resposta de erro de uma solicitação de API HTTP v1 com um token de registro invá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"
}
]
}
}
Observe que ambas as mensagens têm o mesmo código e status, mas a matriz de detalhes
contém valores em tipos diferentes. O primeiro exemplo tem o tipo
type.googleapis.com/google.rpc.BadRequest, indicando um erro nos valores da solicitação. O segundo exemplo com o tipo
type.googleapis.com/google.firebase.fcm.v1.FcmError tem um erro específico do FCM.
Para muitos erros, a matriz de detalhes contém as informações necessárias para depurar
e encontrar uma resolução.
A tabela a seguir lista os códigos de erro da API REST do FCM v1 e as respectivas descrições.
| Código do erro | Etapas de descrição e resolução |
|---|---|
UNSPECIFIED_ERROR Não há mais informações disponíveis sobre esse erro. |
Nenhuma. |
INVALID_ARGUMENT (código do erro HTTP = 400) Os parâmetros da solicitação eram inválidos. Uma extensão do tipo google.rpc.BadRequest é retornada para especificar qual campo era inválido. |
As possíveis causas incluem registro inválido, nome de pacote inválido, mensagem muito grande, chave de dados inválida, TTL inválido ou outros parâmetros inválidos. Registro inválido: verifique o formato do token de registro que você transmite ao servidor. Verifique se ele corresponde ao token de registro que o app cliente recebe ao se registrar no FCM. Não faça truncamento nem adicione caracteres. Nome de pacote inválido: verifique se a mensagem foi endereçada a um token de registro cujo nome do pacote corresponde ao valor transmitido na solicitação. Mensagem muito grande: verifique se o tamanho total dos dados de payload incluídos em uma mensagem não excede os limites do FCM: 4.096 bytes para a maioria das mensagens ou 2.048 bytes no caso de mensagens para tópicos. Inclui as chaves e os valores. Chave de dados inválida: verifique se os dados de payload não contêm uma chave (como "from", "gcm" ou qualquer valor com prefixo "google") usada internamente pelo FCM. Algumas palavras (como collapse_key) também são usadas pelo FCM, mas são permitidas no payload. Nesse caso, o valor do payload será substituído pelo valor do FCM. TTL inválido: verifique se o valor usado em ttl é um número inteiro que representa uma duração em segundos entre 0 e 2.419.200 (4 semanas). Parâmetros inválidos: verifique se os parâmetros fornecidos têm o nome e o tipo corretos. |
UNREGISTERED (código do erro HTTP = 404) A instância do app teve a inscrição cancelada do FCM. Isso geralmente significa que o token usado não é mais válido e deve ser usado um novo. |
Esse erro pode ser causado por tokens de registro ausentes ou tokens com inscrição cancelada. Registro ausente: se o destino da mensagem for um valor token, verifique se a solicitação contém um token de registro.Não registrado: um token de registro atual pode deixar de ser válido em diversos cenários, incluindo: - se o app cliente cancelar a inscrição com o FCM. - se o app cliente tiver a inscrição cancelada automaticamente, algo que pode ocorrer se o usuário desinstalar o aplicativo. Por exemplo, no iOS, se o serviço de feedback de APNs informou o token de APNs como inválido. - se o token de registro expirar, por exemplo, se o Google atualizar os tokens de registro, ou o token de APNs expirou para dispositivos iOS. - Quando o app cliente está atualizado, mas a nova versão não está configurada para receber mensagens. Para todos esses casos, remova o token de registro do servidor do app e pare de usá-lo para enviar mensagens. |
SENDER_ID_MISMATCH (código do erro HTTP = 403) O ID do remetente autenticado é diferente do ID do remetente do token de registro. |
Um token de registro está vinculado a um determinado grupo de remetentes. Quando um app cliente se registra no FCM, os remetentes autorizados a enviar mensagens precisam ser especificados. Use um desses IDs de remetente ao enviar mensagens ao app cliente. Quando você muda para outro remetente, os tokens de registro existentes não funcionam. |
QUOTA_EXCEEDED (código do erro HTTP = 429) O limite de envio foi excedido para o destino da mensagem. Uma extensão do tipo google.rpc.QuotaFailure é retornada para especificar qual cota foi excedida. |
Esse erro pode ser causado por ter excedido a cota de taxa de mensagens, a cota de taxa de mensagens do dispositivo ou a cota de taxa de mensagens de tópico. Taxa de mensagens excedida: a taxa de envio de mensagens está muito alta. Reduza a taxa geral de envio de mensagens. Use a espera exponencial com um delay inicial mínimo de um minuto para tentar enviar novamente as mensagens rejeitadas. Taxa de mensagens do dispositivo excedida: a taxa de mensagens para um determinado dispositivo está muito alta. Consulte Limite de taxa de mensagens para um único dispositivo. Reduza o número de mensagens enviadas a esse dispositivo e use espera exponencial para tentar novamente o envio. Taxa de mensagens de tópico excedida: a taxa de mensagens para assinantes de um determinado tópico está muito alta. Reduza o número de mensagens enviadas a esse tópico e use a espera exponencial com um delay inicial mínimo de 1 minuto para tentar novamente o envio. |
UNAVAILABLE (código do erro HTTP = 503) O servidor está sobrecarregado. |
A solicitação não foi processada a tempo no servidor. Tente enviar a mesma solicitação novamente. Para isso, é necessário: - Respeitar o cabeçalho Retry-After se ele estiver incluído na resposta do servidor de conexão do FCM. - Implementar uma espera exponencial no mecanismo de nova tentativa. Por exemplo, se você esperou um segundo antes da primeira nova tentativa, aguarde pelo menos dois segundos antes da próxima, depois quatro segundos e assim por diante. Se você estiver enviando várias mensagens, considere aplicar a instabilidade. Para mais informações, consulte Como lidar com novas tentativasou verifique o Painel de status do FCM para identificar se há interrupções de serviço em andamento que afetam o FCM. Os remetentes que causam problemas podem ser incluídos em listas de bloqueios. |
INTERNAL (código do erro HTTP = 500) Ocorreu um erro interno desconhecido. |
O servidor encontrou um erro enquanto tentava processar a solicitação. Repita a mesma solicitação seguindo as sugestões em Como lidar com novas tentativas ou verifique o painel de status do FCM. para identificar se há interrupções de serviço em andamento que afetam o FCM. Se o erro persistir, entre em contato com o suporte do Firebase. |
THIRD_PARTY_AUTH_ERROR (código do erro HTTP = 401) O certificado de APNs ou a chave de autenticação por push na Web era inválido ou estava ausente. |
Não foi possível enviar uma mensagem direcionada a um dispositivo iOS ou um registro de push da Web. Verifique a validade das credenciais de desenvolvimento e produção. |
Códigos de erro do SDK Admin
Confira na tabela a seguir os códigos de erro da API Firebase Admin FCM e a descrição de cada erro, incluindo as etapas de resolução recomendadas.
| Código do erro | Etapas de descrição e resolução |
|---|---|
messaging/invalid-argument |
Um argumento inválido foi fornecido a um método do FCM. A mensagem de erro deve conter informações adicionais. |
messaging/invalid-recipient |
O destinatário da mensagem pretendida é inválido. A mensagem de erro deve conter informações adicionais. |
messaging/invalid-payload |
Um objeto de payload de mensagem inválido foi fornecido. A mensagem de erro deve conter informações adicionais. |
messaging/invalid-data-payload-key |
O payload da mensagem de dados contém uma chave inválida. Consulte a
documentação de referência de
DataMessagePayload para mais detalhes sobre chaves restritas.
|
messaging/payload-size-limit-exceeded |
O payload da mensagem fornecido excede os limites de tamanho do FCM. O limite é de 4.096 bytes para a maioria das mensagens. Para mensagens enviadas para tópicos, o limite é de 2.048 bytes. O tamanho do payload total inclui chaves e valores. |
messaging/invalid-options |
Um objeto de opções de mensagem inválido foi fornecido. A mensagem de erro deve conter informações adicionais. |
messaging/invalid-registration-token |
Um token de registro inválido foi fornecido. Verifique se ele corresponde ao token de registro que o app cliente recebe ao se registrar no FCM. Não faça truncagem nem acrescente caracteres adicionais. |
messaging/registration-token-not-registered |
O token de registro fornecido não está registrado. Um token de registro
anteriormente válido pode ter a inscrição cancelada por várias razões,
incluindo:
|
messaging/invalid-package-name |
A mensagem foi encaminhada a um token de registro e o nome do pacote dele
não corresponde à opção
restrictedPackageName fornecida.
|
messaging/message-rate-exceeded |
A taxa de mensagens para um determinado destino é muito alta. Reduza o número de mensagens enviadas a esse dispositivo ou tópico e não tente reenviar mensagens ao mesmo dispositivo imediatamente. |
messaging/device-message-rate-exceeded |
A taxa de mensagens para um determinado dispositivo é muito alta. Reduza o número de mensagens enviadas a esse dispositivo e não tente reenviar mensagens a ele imediatamente. |
messaging/topics-message-rate-exceeded |
A taxa de mensagens para assinantes de um determinado tópico está muito alta. Reduza o número de mensagens enviadas a esse tópico e não tente reenviar mensagens a ele imediatamente. |
messaging/too-many-topics |
Um token de registro foi inscrito no número máximo de tópicos e não pode ser inscrito em mais. |
messaging/invalid-apns-credentials |
Uma mensagem direcionada a um dispositivo Apple não conseguiu ser enviada porque o certificado obrigatório de SSL de APNs não foi enviado ou expirou. Verifique a validade de seus certificados de desenvolvimento e produção. |
messaging/mismatched-credential |
A credencial utilizada para autenticar esse SDK não tem permissão para enviar mensagens ao dispositivo correspondente ao token de registro fornecido. Verifique se o token de registro e a credencial pertencem ao mesmo projeto do Firebase. Consulte Adicionar o Firebase ao seu app para conferir a documentação sobre como autenticar os Firebase Admin SDKs. |
messaging/authentication-error |
O SDK não conseguiu se autenticar com os servidores do FCM. Certifique-se de autenticar o Firebase Admin SDK com uma credencial que tenha as adequadas permissões para enviar mensagens FCM. Consulte Adicionar o Firebase ao seu app para conferir a documentação sobre como autenticar os Firebase Admin SDKs. |
messaging/server-unavailable |
O servidor do FCM não conseguiu processar a solicitação a tempo. Repita
o mesmo pedido, mas é necessário:
|
messaging/internal-error |
O servidor do FCM encontrou um erro enquanto tentava processar a
solicitação. Repita a mesma solicitação seguindo os requisitos
listados na linha messaging/server-unavailable anterior. Se o
erro persistir, informe o problema para nosso
canal de suporte Relatório de bugs.
|
messaging/unknown-error |
Um erro de servidor desconhecido foi retornado. Veja a resposta do servidor bruto na mensagem de erro para saber mais. Se você receber esse erro, informe a mensagem completa no nosso canal de suporte Relatório de bugs. |