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. Ils 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 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 "details" contient des valeurs de différents types. 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 "details" contient les informations dont vous aurez besoin pour déboguer et trouver une solution.
Le tableau suivant répertorie les codes d'erreur de l'API REST FCM v1 et leurs descriptions.
| Code d'erreur | Description et étapes de résolution |
|---|---|
UNSPECIFIED_ERROR Aucune autre information n'est disponible concernant 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 indiquer 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 son 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é envoyé à 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 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é (telle que "from", "gcm" ou toute valeur préfixée par "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. Valeur TTL incorrecte : vérifiez que la valeur utilisée dans ttl est un nombre 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 bon nom et le bon type. |
UNREGISTERED (code d'erreur HTTP = 404) L'instance d'application a été désinscrite de FCM. Cela signifie généralement que le jeton utilisé n'est plus valide et qu'il faut en utiliser un nouveau. |
Cette erreur peut être due à des jetons d'enregistrement manquants ou non enregistrés. Enregistrement manquant : 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, y compris : - si l'application cliente se désinscrit de FCM. – Si l'application cliente est automatiquement désinscrite (ce qui peut se produire si l'utilisateur désinstalle l'application). Par exemple, sur iOS, si le service de commentaires APNs a signalé que le jeton APNs n'était pas 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'application 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'inscrit à 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 passez à un autre expéditeur, les jetons d'enregistrement existants ne fonctionneront pas. |
QUOTA_EXCEEDED (code d'erreur HTTP = 429) : la limite d'envoi a été 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 fréquence des messages, du quota de fréquence des messages de l'appareil ou du quota de fréquence des messages du thème. Taux de messages dépassé : le taux d'envoi de messages est trop élevé. Vous devez réduire le taux global d'envoi de 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. Fréquence de messages pour l'appareil dépassée : la fréquence de messages envoyés à un appareil spécifique est trop élevée. Consultez la limite de fréquence des messages pour 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 le message. Taux de messages par 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 avec un délai initial minimum d'une minute pour réessayer d'envoyer les messages. |
UNAVAILABLE (code d'erreur HTTP = 503) Le serveur est surchargé. |
Le serveur n'a pas pu traiter la requête à temps. Réessayez 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 gigue. Pour en savoir plus, consultez Gérer les nouvelles tentativesou consultez le tableau de bord d'état FCM pour savoir si des interruptions de service en cours affectent FCM. Les expéditeurs qui posent problème risquent d'être ajoutés à la liste des expéditeurs refusés. |
INTERNAL (code d'erreur HTTP = 500) Une erreur interne inconnue s'est produite. |
Le serveur a rencontré une erreur lors du traitement de la demande. Vous pouvez réessayer la même requête en suivant les suggestions de la section Gestion des nouvelles tentatives ou en consultant le tableau de bord de l'état FCM. pour savoir si des interruptions de service sont en cours et affectent 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 étaient non valides ou manquants. |
Un message destiné à un appareil iOS ou à un enregistrement Web Push n'a pas pu être envoyé. 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 pour
DataMessagePayload concernant les clés restreintes.
|
messaging/payload-size-limit-exceeded |
La charge utile du message fourni dépasse les limites 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 à la fois 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'y ajoutez pas de caractères. |
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 était 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 spécifique 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 spécifique 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 spécifique est trop élevé. Réduisez le nombre de messages envoyés pour ce sujet et n'essayez pas immédiatement de les renvoyer. |
messaging/too-many-topics |
Un jeton d'enregistrement a été abonné au nombre maximal de sujets et ne peut plus être abonné à d'autres. |
messaging/invalid-apns-credentials |
Impossible d'envoyer un message à un appareil Apple, 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 les identifiants 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 des identifiants 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 demande à 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 respectant les exigences listées dans la ligne messaging/server-unavailable précédente. Si l'erreur persiste, veuillez la signaler sur notre canal d'assistance Rapport de bug.
|
messaging/unknown-error |
Une erreur 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 ce message d'erreur, veuillez le signaler en intégralité sur notre chaîne d'assistance Bug Report. |