Codes d'erreur REST pour l'API HTTP v1
Les réponses d'erreur HTTP pour l'API HTTP v1 contiennent un code d'erreur, un message d'erreur et un état d'erreur. Elles peuvent également contenir un tableau details avec plus de détails sur l'erreur.
Voici deux exemples de réponses d'erreur :
Exemple 1 : Réponse d'erreur d'une requête API HTTP v1 avec une valeur non valide dans un message de données
{
"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"
}
]
}
]
}
}
Exemple 2 : Réponse d'erreur d'une requête API HTTP v1 avec un jeton d'enregistrement non valide
{
"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"
}
]
}
}
Notez que les deux messages ont le même code et le même état, mais que le tableau de détails contient des valeurs de types différents. Le premier exemple est de type type.googleapis.com/google.rpc.BadRequest, ce qui indique une erreur dans les valeurs de la requête. Le deuxième exemple avec le type type.googleapis.com/google.firebase.fcm.v1.FcmError comporte une erreur spécifique à FCM.
Pour de nombreuses erreurs, le tableau de détails contient les informations dont vous aurez besoin pour déboguer et trouver une solution.
Le tableau suivant liste les codes d'erreur de l'API REST FCM v1 et leur description.
| Code d'erreur | Description et étapes de résolution |
|---|---|
UNSPECIFIED_ERROR Aucune autre information n'est disponible sur cette erreur. |
Aucune. |
INVALID_ARGUMENT (code d'erreur HTTP = 400) Les paramètres de la requête n'étaient pas valides. Une extension de type google.rpc.BadRequest est renvoyée pour spécifier le champ non valide. |
Les causes potentielles incluent un enregistrement non valide, un nom de package non valide, un message trop volumineux, une clé de données non valide, une valeur TTL non valide ou d'autres paramètres non valides. Enregistrement non valide : vérifiez le format du jeton d'enregistrement que vous transmettez au serveur. Assurez-vous qu'il correspond au jeton d'enregistrement que l'application cliente reçoit lors de l'enregistrement auprès de FCM. Ne tronquez pas le jeton et n'ajoutez pas de caractères supplémentaires. Nom de package non valide : assurez-vous que le message a été adressé à un jeton d'enregistrement dont le nom de package correspond à la valeur transmise dans la requête. Message trop volumineux : vérifiez que la taille totale des données de charge utile incluses dans un message ne dépasse pas les limites de FCM : 4 096 octets pour la plupart des messages, ou 2 048 octets pour les messages envoyés à des thèmes. Cela inclut à la fois les clés et les valeurs. Clé de données non valide : vérifiez que les données de la charge utile ne contiennent pas de clé (par exemple, "from", "gcm" ou toute valeur précédée de "google") utilisée en interne par FCM. Notez que certains mots (comme collapse_key) sont également utilisés par FCM, mais sont autorisés dans la charge utile. Dans ce cas, la valeur de la charge utile sera remplacée par la valeur FCM. TTL non valide : vérifiez que la valeur utilisée dans ttl est un entier représentant une durée en secondes comprise entre 0 et 2 419 200 (4 semaines). Paramètres non valides : vérifiez que les paramètres fournis ont le nom et le type appropriés. |
UNREGISTERED (code d'erreur HTTP = 404) L'instance de l'application a été désenregistrée de FCM. Cela signifie généralement que le jeton utilisé n'est plus valide et qu'un nouveau jeton doit être utilisé. |
Cette erreur peut être due à des jetons d'enregistrement manquants ou non enregistrés. Missing Registration : si la cible du message est une valeur token, vérifiez que la requête contient un jeton d'enregistrement.Non enregistré : un jeton d'enregistrement existant peut cesser d'être valide dans plusieurs cas de figure, y compris : - Si l'application cliente se désinscrit de FCM. - Si l'application cliente est automatiquement désenregistrée, ce qui peut se produire si l'utilisateur désinstalle l'application. Par exemple, sur iOS, si le service de commentaires APNs a signalé le jeton APNs comme non valide. - Si le jeton d'enregistrement expire (par exemple, Google peut décider d'actualiser les jetons d'enregistrement, ou le jeton APNs a expiré pour les appareils iOS). : si l'application cliente est mise à jour, mais que la nouvelle version n'est pas configurée pour recevoir des messages. Dans tous ces cas, supprimez ce jeton d'enregistrement du serveur d'applications et arrêtez de l'utiliser pour envoyer des messages. |
SENDER_ID_MISMATCH (code d'erreur HTTP = 403) L'ID de l'expéditeur authentifié est différent de l'ID de l'expéditeur pour le jeton d'enregistrement. |
Un jeton d'enregistrement est associé à un certain groupe d'expéditeurs. Lorsqu'une application cliente s'enregistre auprès de FCM, elle doit spécifier les expéditeurs autorisés à envoyer des messages. Vous devez utiliser l'un de ces ID d'expéditeur lorsque vous envoyez des messages à l'application cliente. Si vous changez d'expéditeur, les jetons d'enregistrement existants ne fonctionneront pas. |
QUOTA_EXCEEDED (code d'erreur HTTP = 429) : limite d'envoi dépassée pour la cible du message. Une extension de type google.rpc.QuotaFailure est renvoyée pour spécifier le quota qui a été dépassé. |
Cette erreur peut être due à un dépassement du quota de débit de messages, du quota de débit de messages par appareil ou du quota de débit de messages par sujet. Taux de messages dépassé : le taux d'envoi des messages est trop élevé. Vous devez réduire la fréquence globale d'envoi des messages. Utilisez un intervalle exponentiel entre les tentatives avec un délai initial minimal d'une minute pour réessayer d'envoyer les messages refusés. Device message rate exceeded : le taux de messages envoyés à un appareil particulier est trop élevé. Consultez Limitation du débit des messages vers un seul appareil. Réduisez le nombre de messages envoyés à cet appareil et utilisez un intervalle exponentiel entre les tentatives pour réessayer d'envoyer les messages. Taux de messages du sujet dépassé : le taux de messages envoyés aux abonnés d'un sujet particulier est trop élevé. Réduisez le nombre de messages envoyés pour ce sujet et utilisez un intervalle exponentiel entre les tentatives avec un délai initial minimal d'une minute pour réessayer l'envoi. |
UNAVAILABLE (code d'erreur HTTP = 503) : le serveur est surchargé. |
Le serveur n'a pas pu traiter la requête à temps. Réessayez d'envoyer la même requête, mais vous devez : - respecter l'en-tête Retry-After s'il est inclus dans la réponse du serveur de connexion FCM. - Implémentez un intervalle exponentiel entre les tentatives dans votre mécanisme de nouvelle tentative. (par exemple, si vous avez attendu une seconde avant la première nouvelle tentative, attendez au moins deux secondes avant la suivante, puis quatre secondes, et ainsi de suite). Si vous envoyez plusieurs messages, envisagez d'appliquer une instabilité. Pour en savoir plus, consultez Gérer les nouvelles tentativesou consultez le tableau de bord d'état de FCM pour identifier si des interruptions de service affectent FCM. Les expéditeurs qui causent des problèmes risquent d'être ajoutés à une liste de blocage. |
INTERNAL (code d'erreur HTTP = 500) Une erreur interne inconnue s'est produite. |
Le serveur a rencontré une erreur lors du traitement de la requête. Vous pouvez réessayer d'envoyer la même requête en suivant les suggestions de la section Gérer les nouvelles tentatives ou en consultant le tableau de bord d'état de FCM. pour savoir si des interruptions de service affectent actuellement FCM. Si l'erreur persiste, veuillez contacter l'assistance Firebase. |
THIRD_PARTY_AUTH_ERROR (code d'erreur HTTP = 401) Le certificat APNs ou la clé d'authentification Web Push n'est pas valide ou est manquant. |
Impossible d'envoyer un message ciblant un appareil iOS ou une inscription à des notifications push Web. Vérifiez la validité de vos identifiants de développement et de production. |
Codes d'erreur du SDK Admin
Le tableau suivant liste les codes d'erreur de l'API Firebase Admin FCM et leur description, y compris les étapes de résolution recommandées.
| Code d'erreur | Description et étapes de résolution |
|---|---|
messaging/invalid-argument |
Un argument non valide a été fourni à une méthode FCM. Le message d'erreur doit contenir des informations supplémentaires. |
messaging/invalid-recipient |
Le destinataire du message n'est pas valide. Le message d'erreur doit contenir des informations supplémentaires. |
messaging/invalid-payload |
Un objet de charge utile de message non valide a été fourni. Le message d'erreur doit contenir des informations supplémentaires. |
messaging/invalid-data-payload-key |
La charge utile du message de données contient une clé non valide. Consultez la documentation de référence sur
DataMessagePayload pour connaître les clés limitées.
|
messaging/payload-size-limit-exceeded |
La charge utile du message fournie dépasse la limite de taille de FCM. La limite est de 4 096 octets pour la plupart des messages. Pour les messages envoyés à des thèmes, la limite est de 2 048 octets. La taille totale de la charge utile inclut les clés et les valeurs. |
messaging/invalid-options |
Un objet d'options de message non valide a été fourni. Le message d'erreur doit contenir des informations supplémentaires. |
messaging/invalid-registration-token |
Le jeton d'enregistrement fourni n'est pas valide. Assurez-vous qu'il correspond au jeton d'enregistrement que l'application cliente reçoit lors de l'enregistrement auprès de FCM. Ne le tronquez pas et n'ajoutez pas de caractères supplémentaires. |
messaging/registration-token-not-registered |
Le jeton d'enregistrement fourni n'est pas enregistré. Un jeton d'enregistrement précédemment valide peut être désenregistré pour diverses raisons, y compris :
|
messaging/invalid-package-name |
Le message a été adressé à un jeton d'enregistrement dont le nom de package ne correspond pas à l'option
restrictedPackageName fournie.
|
messaging/message-rate-exceeded |
Le taux de messages envoyés à une cible particulière est trop élevé. Réduisez le nombre de messages envoyés à cet appareil ou à ce sujet, et ne réessayez pas immédiatement d'envoyer des messages à cette cible. |
messaging/device-message-rate-exceeded |
Le taux de messages envoyés à un appareil particulier est trop élevé. Réduisez le nombre de messages envoyés à cet appareil et ne réessayez pas immédiatement d'envoyer des messages à cet appareil. |
messaging/topics-message-rate-exceeded |
Le taux de messages envoyés aux abonnés d'un sujet particulier est trop élevé. Réduisez le nombre de messages envoyés pour ce sujet et ne réessayez pas immédiatement d'envoyer des messages à ce sujet. |
messaging/topics-subscription-rate-exceeded |
Le taux de requêtes de gestion des abonnements pour un sujet particulier est trop élevé. Réduisez le nombre de requêtes envoyées pour ce sujet et ne relancez pas immédiatement la requête. |
messaging/too-many-topics |
Un jeton d'enregistrement a été abonné au nombre maximal de thèmes et ne peut plus être abonné à d'autres thèmes. |
messaging/invalid-apns-credentials |
Un message ciblant un appareil Apple n'a pas pu être envoyé, car le certificat SSL APNs requis n'a pas été importé ou a expiré. Vérifiez la validité de vos certificats de développement et de production. |
messaging/mismatched-credential |
L'identifiant utilisé pour authentifier ce SDK n'est pas autorisé à envoyer des messages à l'appareil correspondant au jeton d'enregistrement fourni. Assurez-vous que l'identifiant et le jeton d'enregistrement appartiennent au même projet Firebase. Consultez Ajouter Firebase à votre application pour obtenir de la documentation sur l'authentification des Firebase Admin SDK. |
messaging/authentication-error |
Le SDK n'a pas pu s'authentifier auprès des serveurs FCM. Assurez-vous d'authentifier Firebase Admin SDK avec un identifiant disposant des autorisations appropriées pour envoyer des messages FCM. Consultez Ajouter Firebase à votre application pour obtenir de la documentation sur l'authentification des Firebase Admin SDK. |
messaging/server-unavailable |
Le serveur FCM n'a pas pu traiter la requête à temps. Vous devez relancer la même requête, mais vous devez :
|
messaging/internal-error |
Le serveur FCM a rencontré une erreur lors du traitement de la requête. Vous pouvez réessayer la même requête en suivant les exigences listées dans la ligne messaging/server-unavailable précédente. Si l'erreur persiste, veuillez signaler le problème via notre canal d'assistance Rapport de bug.
|
messaging/unknown-error |
Une erreur de serveur inconnue a été renvoyée. Pour en savoir plus, consultez la réponse brute du serveur dans le message d'erreur. Si vous recevez cette erreur, veuillez signaler le message d'erreur complet à notre canal d'assistance Rapport de bug. |