FCM-Fehlercodes

REST-Fehlercodes für die HTTP v1 API

HTTP-Fehlerantworten für die HTTP v1 API enthalten einen Fehlercode, eine Fehlermeldung und einen Fehlerstatus. Sie können auch ein details-Array mit weiteren Details zum Fehler enthalten.

Hier sind zwei Beispiele für Fehlerantworten:

Beispiel 1: Fehlerantwort von einer HTTP v1 API-Anfrage mit einem ungültigen Wert in einer Datennachricht

{
  "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"
          }
        ]
      }
    ]
  }
}

Beispiel 2: Fehlerantwort von einer HTTP v1 API-Anfrage mit einem ungültigen Registrierungstoken

{
  "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"
      }
    ]
   }
}

Beide Nachrichten haben denselben Code und Status, aber das Details-Array enthält Werte in verschiedenen Typen. Das erste Beispiel hat den Typ type.googleapis.com/google.rpc.BadRequest, der auf einen Fehler in den Anfrage-Werten hinweist. Das zweite Beispiel mit dem Typ type.googleapis.com/google.firebase.fcm.v1.FcmError hat einen FCM-spezifischen Fehler. Bei vielen Fehlern enthält das Details-Array die Informationen, die Sie zum Debuggen und Finden einer Lösung benötigen.

In der folgenden Tabelle sind die Fehlercodes der FCM v1 REST API und ihre Beschreibungen aufgeführt.

Fehlercode Beschreibung und Lösungsschritte
UNSPECIFIED_ERROR Es sind keine weiteren Informationen zu diesem Fehler verfügbar. Keine.
INVALID_ARGUMENT (HTTP-Fehlercode = 400) Die Anfrageparameter waren ungültig. Es wird eine Erweiterung vom Typ google.rpc.BadRequest zurückgegeben, um anzugeben, welches Feld ungültig war. Mögliche Ursachen sind eine ungültige Registrierung, ein ungültiger Paketname, eine zu große Nachricht, ein ungültiger Datenschlüssel, eine ungültige TTL oder andere ungültige Parameter.
Ungültige Registrierung: Prüfen Sie das Format des Registrierungstokens, das Sie an den Server übergeben. Es muss mit dem Registrierungstoken übereinstimmen, das die Client-App bei der Registrierung bei FCM erhält. Kürzen Sie das Token nicht und fügen Sie keine zusätzlichen Zeichen hinzu.
Ungültiger Paketname: Achten Sie darauf, dass die Nachricht an ein Registrierungstoken adressiert wurde, dessen Paketname mit dem in der Anfrage übergebenen Wert übereinstimmt.
Nachricht zu groß: Achten Sie darauf, dass die Gesamtgröße der in einer Nachricht enthaltenen Nutzlastdaten die FCM-Limits nicht überschreitet: 4.096 Byte für die meisten Nachrichten oder 2.048 Byte für Nachrichten an Themen. Dazu gehören sowohl die Schlüssel als auch die Werte.
Ungültiger Datenschlüssel: Achten Sie darauf, dass die Nutzlastdaten keinen Schlüssel enthalten (z. B. „from“, „gcm“ oder einen Wert mit dem Präfix „google“), der intern von FCM verwendet wird. Einige Wörter (z. B. „collapse_key“) werden auch von FCM verwendet, sind aber in der Nutzlast zulässig. In diesem Fall wird der Nutzlastwert durch den FCM-Wert überschrieben.
Ungültige TTL: Achten Sie darauf,dass der in „ttl“ verwendete Wert eine Ganzzahl ist,die eine Dauer in Sekunden zwischen 0 und 2.419.200 (4 Wochen) darstellt.
Ungültige Parameter: Prüfen Sie, ob die angegebenen Parameter den richtigen Namen und Typ haben.
UNREGISTERED (HTTP-Fehlercode = 404) Die App-Instanz wurde von FCM abgemeldet. Das bedeutet in der Regel, dass das verwendete Token nicht mehr gültig ist und ein neues verwendet werden muss. Dieser Fehler kann durch fehlende oder abgemeldete Registrierungstokens verursacht werden.
Fehlende Registrierung: Wenn das Ziel der Nachricht ein token Wert ist, prüfen Sie, ob die Anfrage ein Registrierungstoken enthält.
Nicht registriert: Ein vorhandenes Registrierungstoken kann in verschiedenen Szenarien ungültig werden:
– Wenn die Client-App sich von FCM abmeldet.
– Wenn die Client-App automatisch abgemeldet wird, z. B. wenn der Nutzer die Anwendung deinstalliert. Unter iOS kann das der Fall sein, wenn der APNs Feedback Service das APNs-Token als ungültig gemeldet hat.
– Wenn das Registrierungstoken abläuft (z. B. wenn Google beschließt, Registrierungstokens zu aktualisieren, oder das APNs-Token für iOS-Geräte abgelaufen ist).
– Wenn die Client-App aktualisiert wird, die neue Version aber nicht für den Empfang von Nachrichten konfiguriert ist.
Entfernen Sie in all diesen Fällen dieses Registrierungstoken vom App-Server und verwenden Sie es nicht mehr zum Senden von Nachrichten.
SENDER_ID_MISMATCH (HTTP-Fehlercode = 403) Die authentifizierte Absender-ID unterscheidet sich von der Absender-ID für das Registrierungstoken. Ein Registrierungstoken ist an eine bestimmte Gruppe von Absendern gebunden. Wenn eine Client-App sich für FCM registriert, muss sie angeben, welche Absender Nachrichten senden dürfen. Verwenden Sie eine dieser Absender-IDs, wenn Sie Nachrichten an die Client-App senden. Wenn Sie zu einem anderen Absender wechseln, funktionieren die vorhandenen Registrierungstokens nicht.
QUOTA_EXCEEDED (HTTP-Fehlercode = 429) Das Sendelimit für das Nachrichtenziel wurde überschritten. Es wird eine Erweiterung vom Typ google.rpc.QuotaFailure zurückgegeben, um anzugeben, welches Kontingent überschritten wurde. Dieser Fehler kann durch ein überschrittenes Kontingent für die Nachrichtenrate, ein überschrittenes Kontingent für die Nachrichtenrate pro Gerät oder ein überschrittenes Kontingent für die Nachrichtenrate pro Thema verursacht werden.
Nachrichtenrate überschritten: Die Sendegeschwindigkeit von Nachrichten ist zu hoch. Sie müssen die Gesamtrate, mit der Sie Nachrichten senden, reduzieren. Verwenden Sie exponentiellen Backoff mit einer anfänglichen Mindestverzögerung von 1 Minute, um abgelehnte Nachrichten noch einmal zu senden.
Nachrichtenrate pro Gerät überschritten: Die Rate der Nachrichten an ein bestimmtes Gerät ist zu hoch. Weitere Informationen finden Sie unter Nachrichtenrate für ein einzelnes Gerät. Reduzieren Sie die Anzahl der an dieses Gerät gesendeten Nachrichten und verwenden Sie exponentiellen Backoff, um das Senden noch einmal zu versuchen.
Nachrichtenrate pro Thema überschritten: Die Rate der Nachrichten an Abonnenten eines bestimmten Themas ist zu hoch. Reduzieren Sie die Anzahl der für dieses Thema gesendeten Nachrichten und verwenden Sie exponentiellen Backoff mit einer anfänglichen Mindestverzögerung von 1 Minute, um das Senden noch einmal zu versuchen.
UNAVAILABLE (HTTP-Fehlercode = 503) Der Server ist überlastet. Der Server konnte die Anfrage nicht rechtzeitig verarbeiten. Versuchen Sie es noch einmal mit derselben Anfrage, aber beachten Sie Folgendes:
- Beachten Sie den Header „Retry-After“, falls er in der Antwort vom FCM-Verbindungsserver enthalten ist.
– Implementieren Sie exponentiellen Backoff in Ihrem Wiederholungsmechanismus. Wenn Sie beispielsweise eine Sekunde vor dem ersten Wiederholungsversuch gewartet haben, warten Sie mindestens zwei Sekunden vor dem nächsten, dann vier Sekunden usw. Wenn Sie mehrere Nachrichten senden, sollten Sie Jittering anwenden. Weitere Informationen finden Sie unter Wiederholungsversuche verarbeitenoder sehen Sie im FCM-Status-Dashboard nach, ob es aktuelle Dienstunterbrechungen gibt, die sich auf FCM auswirken. Absender, die Probleme verursachen, werden möglicherweise auf die Sperrliste gesetzt.
INTERNAL (HTTP-Fehlercode = 500) Ein unbekannter interner Fehler ist aufgetreten. Auf dem Server ist beim Versuch, die Anfrage zu verarbeiten, ein Fehler aufgetreten. Sie können es noch einmal mit derselben Anfrage versuchen. Folgen Sie dazu den Vorschlägen unter Wiederholungsversuche verarbeiten oder sehen Sie im FCM-Status-Dashboard nach. ob es aktuelle Dienstunterbrechungen gibt, die sich auf FCM auswirken. Wenn der Fehler weiterhin auftritt, wenden Sie sich an den Firebase-Support.
THIRD_PARTY_AUTH_ERROR (HTTP-Fehlercode = 401) Das APNs-Zertifikat oder der Web-Push-Authentifizierungsschlüssel war ungültig oder fehlte. Eine Nachricht, die an ein iOS-Gerät oder eine Web-Push-Registrierung gesendet werden sollte, konnte nicht gesendet werden. Prüfen Sie die Gültigkeit Ihrer Anmeldedaten für die Entwicklung und Produktion.

Admin SDK-Fehlercodes

In der folgenden Tabelle sind die Fehlercodes der Firebase Admin FCM API und ihre Beschreibungen aufgeführt, einschließlich empfohlener Lösungsschritte.

Fehlercode Beschreibung und Lösungsschritte
messaging/invalid-argument Einer FCM Methode wurde ein ungültiges Argument übergeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-recipient Der beabsichtigte Empfänger der Nachricht ist ungültig. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-payload Es wurde ein ungültiges Nutzlastobjekt für die Nachricht übergeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-data-payload-key Die Nutzlast der Datennachricht enthält einen ungültigen Schlüssel. In der Referenzdokumentation für DataMessagePayload finden Sie Informationen zu eingeschränkten Schlüsseln.
messaging/payload-size-limit-exceeded Die angegebene Nutzlast der Nachricht überschreitet die FCM Größenlimits. Das Limit beträgt für die meisten Nachrichten 4.096 Byte. Für Nachrichten, die an Themen gesendet werden, beträgt das Limit 2.048 Byte. Die Gesamtgröße der Nutzlast umfasst sowohl Schlüssel als auch Werte.
messaging/invalid-options Es wurde ein ungültiges Optionenobjekt für die Nachricht übergeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-registration-token Es wurde ein ungültiges Registrierungstoken übergeben. Es muss mit dem Registrierungs token übereinstimmen, das die Client-App bei der Registrierung bei FCM erhält. Kürzen Sie es nicht und fügen Sie keine zusätzlichen Zeichen hinzu.
messaging/registration-token-not-registered Das angegebene Registrierungstoken ist nicht registriert. Ein zuvor gültiges Registrierungstoken kann aus verschiedenen Gründen abgemeldet werden, einschließlich:
  • Die Client-App hat sich von FCM abgemeldet.
  • Die Client-App wurde automatisch abgemeldet. Das kann passieren, wenn der Nutzer die Anwendung deinstalliert oder wenn der APNs Feedback Service auf Apple-Plattformen das APNs-Token als ungültig gemeldet hat.
  • Das Registrierungstoken ist abgelaufen. Google kann beispielsweise beschließen, Registrierungstokens zu aktualisieren, oder das APNs-Token für Apple-Geräte ist abgelaufen.
  • Die Client-App wurde aktualisiert, die neue Version ist aber nicht für den Empfang von Nachrichten konfiguriert.
Entfernen Sie in all diesen Fällen dieses Registrierungstoken und verwenden Sie es nicht mehr zum Senden von Nachrichten.
messaging/invalid-package-name Die Nachricht wurde an ein Registrierungstoken adressiert, dessen Paketname nicht mit der angegebenen restrictedPackageName Option übereinstimmt.
messaging/message-rate-exceeded Die Rate der Nachrichten an ein bestimmtes Ziel ist zu hoch. Reduzieren Sie die Anzahl der an dieses Gerät oder Thema gesendeten Nachrichten und versuchen Sie nicht sofort, Nachrichten an dieses Ziel zu senden.
messaging/device-message-rate-exceeded Die Rate der Nachrichten an ein bestimmtes Gerät ist zu hoch. Reduzieren Sie die Anzahl der an dieses Gerät gesendeten Nachrichten und versuchen Sie nicht sofort, Nachrichten an dieses Gerät zu senden.
messaging/topics-message-rate-exceeded Die Rate der Nachrichten an Abonnenten eines bestimmten Themas ist zu hoch. Reduzieren Sie die Anzahl der für dieses Thema gesendeten Nachrichten und versuchen Sie nicht sofort, Nachrichten an dieses Thema zu senden.
messaging/too-many-topics Ein Registrierungstoken wurde für die maximale Anzahl von Themen abonniert und kann nicht für weitere Themen abonniert werden.
messaging/invalid-apns-credentials Eine Nachricht, die an ein Apple-Gerät gesendet werden sollte, konnte nicht gesendet werden, weil das erforderliche APNs-SSL-Zertifikat nicht hochgeladen wurde oder abgelaufen ist. Prüfen Sie die Gültigkeit Ihrer Zertifikate für die Entwicklung und Produktion.
messaging/mismatched-credential Die Anmeldedaten, die zur Authentifizierung dieses SDK verwendet wurden, haben keine Berechtigung zum Senden von Nachrichten an das Gerät, das dem angegebenen Registrierungs token entspricht. Achten Sie darauf, dass die Anmeldedaten und das Registrierungstoken zum selben Firebase-Projekt gehören. Unter Firebase zu Ihrer App hinzufügen finden Sie eine Dokumentation zur Authentifizierung der Firebase Admin SDKs.
messaging/authentication-error Das SDK konnte sich nicht bei den FCM Servern authentifizieren. Achten Sie darauf, dass Sie das Firebase Admin SDK mit Anmeldedaten authentifizieren, die die entsprechenden Berechtigungen zum Senden von FCM Nachrichten haben. Unter Firebase zu Ihrer App hinzufügen finden Sie eine Dokumentation zur Authentifizierung der Firebase Admin SDKs.
messaging/server-unavailable Der FCM Server konnte die Anfrage nicht rechtzeitig verarbeiten. Versuchen Sie es noch einmal mit derselben Anfrage, aber beachten Sie Folgendes:
  • Beachten Sie den Retry-After Header, falls er in der Antwort vom FCM Verbindungsserver enthalten ist.
  • Implementieren Sie exponentiellen Backoff in Ihrem Wiederholungsmechanismus. Wenn Sie beispielsweise eine Sekunde vor dem ersten Wiederholungsversuch gewartet haben, warten Sie mindestens zwei Sekunden vor dem nächsten, dann vier Sekunden usw. Wenn Sie mehrere Nachrichten senden, verzögern Sie jede Nachricht unabhängig um einen zusätzlichen zufälligen Betrag, um zu vermeiden, dass gleichzeitig eine neue Anfrage für alle Nachrichten gesendet wird.
Absender, die Probleme verursachen, werden möglicherweise auf die Sperrliste gesetzt.
messaging/internal-error Auf dem FCM Server ist beim Versuch, die Anfrage zu verarbeiten, ein Fehler aufgetreten. Sie können es noch einmal mit derselben Anfrage versuchen. Beachten Sie dabei die Anforderungen, die in der vorherigen messaging/server-unavailable Zeile aufgeführt sind. Wenn der Fehler weiterhin auftritt, melden Sie das Problem bitte über unseren Supportkanal für Fehlerberichte.
messaging/unknown-error Es wurde ein unbekannter Serverfehler zurückgegeben. Weitere Informationen finden Sie in der Rohantwort des Servers in der Fehlermeldung. Wenn Sie diesen Fehler erhalten, melden Sie die vollständige Fehlermeldung bitte über unseren Supportkanal für Fehlerberichte.