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 Array „details“ enthält Werte unterschiedlicher Typen. Das erste Beispiel hat den Typ type.googleapis.com/google.rpc.BadRequest, der auf einen Fehler in den Anfragewerten hinweist. Das zweite Beispiel mit dem Typ type.googleapis.com/google.firebase.fcm.v1.FcmError enthält einen FCM-spezifischen Fehler. Bei vielen Fehlern enthält das Array „details“ die Informationen, die Sie zur Fehlerbehebung und zum 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. Eine Erweiterung vom Typ google.rpc.BadRequest wird 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. Achten Sie darauf, dass es mit dem Registrierungstoken übereinstimmt, 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: Die Nachricht muss an ein Registrierungstoken adressiert sein, dessen Paketname mit dem in der Anfrage übergebenen Wert übereinstimmt.
Nachricht zu groß: Prüfen Sie, ob 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. Dies gilt sowohl für die Schlüssel als auch für die Werte.
Ungültiger Datenschlüssel: Prüfen Sie, ob die Nutzlastdaten einen Schlüssel enthalten, der intern von FCM verwendet wird (z. B. „from“, „gcm“ oder ein Wert mit dem Präfix „google“). Beachten Sie, dass einige Wörter (z. B. collapse_key) auch von FCM verwendet werden, aber in der Nutzlast zulässig sind. In diesem Fall wird der Nutzlastwert durch den FCM-Wert überschrieben.
Ungültige TTL: Prüfen Sie,ob der für „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 nicht registrierte 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, z. B.:
– Wenn die Client-App die Registrierung bei FCM aufhebt.
– Wenn die Client-App automatisch abgemeldet wird, was passieren kann, wenn der Nutzer die Anwendung deinstalliert. Beispiel: Wenn der APNs-Feedbackdienst unter iOS das APNs-Token als ungültig gemeldet hat.
– Wenn das Registrierungstoken abläuft (z. B. wenn Google Registrierungstoken aktualisiert 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.
In all diesen Fällen sollten Sie dieses Registrierungstoken vom Anwendungsserver entfernen und nicht mehr zum Senden von Nachrichten verwenden.
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 sich eine Client-App für FCM registriert, muss sie angeben, welche Absender Nachrichten senden dürfen. Sie sollten eine dieser Absender-IDs verwenden, wenn Sie Nachrichten an die Client-App senden. Wenn Sie zu einem anderen Absender wechseln, funktionieren die vorhandenen Registrierungstokens nicht mehr.
QUOTA_EXCEEDED (HTTP-Fehlercode = 429) Sendebeschränkung für das Nachrichtenziel überschritten. Eine Erweiterung vom Typ google.rpc.QuotaFailure wird zurückgegeben, um anzugeben, welches Kontingent überschritten wurde. Dieser Fehler kann durch eine Überschreitung des Ratenkontingents für Nachrichten, des Ratenkontingents für Gerätenachrichten oder des Ratenkontingents für Themennachrichten verursacht werden.
Nachrichtenrate überschritten: Die Senderate von Nachrichten ist zu hoch. Sie müssen die Gesamtrate reduzieren, mit der Sie Nachrichten senden. Verwenden Sie einen exponentiellen Backoff mit einer anfänglichen Mindestverzögerung von 1 Minute, um abgelehnte Nachrichten noch einmal zu senden.
Gerätenachrichtenrate überschritten: Die Rate der Nachrichten an ein bestimmtes Gerät ist zu hoch. Weitere Informationen finden Sie unter Nachrichtenratenlimit für ein einzelnes Gerät. Reduzieren Sie die Anzahl der an dieses Gerät gesendeten Nachrichten und verwenden Sie den exponentiellen Backoff, um das Senden zu wiederholen.
Topic 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 verwenden Sie den exponentiellen Backoff mit einer anfänglichen Mindestverzögerung von 1 Minute, um den Sendevorgang zu wiederholen.
UNAVAILABLE (HTTP-Fehlercode = 503) Der Server ist überlastet. Der Server konnte die Anfrage nicht rechtzeitig verarbeiten. Wiederholen Sie dieselbe Anfrage, aber beachten Sie Folgendes:
– Beachten Sie den Retry-After-Header, wenn er in der Antwort des FCM-Verbindungsservers enthalten ist.
– Implementieren Sie einen exponentiellen Backoff in Ihrem Wiederholungsmechanismus. Wenn Sie beispielsweise vor dem ersten Wiederholungsversuch eine Sekunde gewartet haben, warten Sie vor dem nächsten mindestens zwei Sekunden, dann vier Sekunden usw. Wenn Sie mehrere Nachrichten senden, sollten Sie Jittering anwenden. Weitere Informationen finden Sie unter Umgang mit Wiederholungsversuchen. Sie können auch im FCM-Status-Dashboard nachsehen, ob es laufende 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. Beim Verarbeiten der Anfrage ist ein Serverfehler aufgetreten. Sie können dieselbe Anfrage noch einmal senden. Folgen Sie dazu den Vorschlägen unter Wiederholungen verarbeiten oder prüfen Sie das FCM-Status-Dashboard. um festzustellen, ob es aktuelle Dienstunterbrechungen gibt, die sich auf FCM auswirken. Wenn der Fehler weiterhin auftritt, wenden Sie sich bitte 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 gerichtet war, konnte nicht gesendet werden. Prüfen Sie die Gültigkeit Ihrer Entwicklungs- und Produktionsanmeldedaten.

Admin SDK-Fehlercodes

In der folgenden Tabelle sind die Fehlercodes der Firebase Admin FCM API und ihre Beschreibungen aufgeführt, einschließlich empfohlener Schritte zur Fehlerbehebung.

Fehlercode Beschreibung und Lösungsschritte
messaging/invalid-argument An eine FCM-Methode wurde ein ungültiges Argument übergeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-recipient Der vorgesehene Empfänger der Nachricht ist ungültig. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-payload Es wurde ein ungültiges Nachrichten-Nutzlastobjekt angegeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-data-payload-key Die Nutzlast der Datennachricht enthält einen ungültigen Schlüssel. Weitere Informationen zu eingeschränkten Schlüsseln finden Sie in der Referenzdokumentation zu DataMessagePayload.
messaging/payload-size-limit-exceeded Die bereitgestellte Nachrichtennutzlast überschreitet die Größenbeschränkungen von FCM. 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 Objekt für Nachrichtenoptionen angegeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-registration-token Ungültiges Registrierungstoken angegeben. Achten Sie darauf, dass es mit dem Registrierungstoken übereinstimmt, das die Client-App bei der Registrierung bei FCM erhält. Kürzen Sie sie 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, z. B.:
  • Die Client-App hat sich von FCM abgemeldet.
  • Die Registrierung der Client-App wurde automatisch aufgehoben. Das kann passieren, wenn der Nutzer die Anwendung deinstalliert oder wenn auf Apple-Plattformen der APNs-Feedbackdienst das APNs-Token als ungültig gemeldet hat.
  • Das Registrierungstoken ist abgelaufen. Google kann beispielsweise beschließen, Registrierungstokens zu aktualisieren, oder das APNs-Token ist für Apple-Geräte abgelaufen.
  • Die Client-App wurde aktualisiert, die neue Version ist jedoch 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 war an ein Registrierungstoken adressiert, dessen Paketname nicht mit der angegebenen Option restrictedPackageName übereinstimmt.
messaging/message-rate-exceeded Die Rate der Nachrichten an ein bestimmtes Ziel ist zu hoch. Reduzieren Sie die Anzahl der Nachrichten, die an dieses Gerät oder Thema gesendet werden, und versuchen Sie nicht sofort, die Nachricht noch einmal 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, die Nachricht noch einmal 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/topics-subscription-rate-exceeded Die Rate der Aboverwaltungsanfragen für ein bestimmtes Thema ist zu hoch. Reduzieren Sie die Anzahl der für dieses Thema gesendeten Anfragen und wiederholen Sie die Anfrage nicht sofort.
messaging/too-many-topics Ein Registrierungstoken wurde für die maximale Anzahl von Themen abonniert und kann nicht mehr abonniert werden.
messaging/invalid-apns-credentials Eine Nachricht, die an ein Apple-Gerät gerichtet war, konnte nicht gesendet werden, weil das erforderliche APNs-SSL-Zertifikat nicht hochgeladen wurde oder abgelaufen ist. Prüfen Sie die Gültigkeit Ihrer Entwicklungs- und Produktionszertifikate.
messaging/mismatched-credential Die zur Authentifizierung dieses SDKs verwendeten Anmeldedaten sind nicht berechtigt, Nachrichten an das Gerät zu senden, das dem angegebenen Registrierungstoken entspricht. Achten Sie darauf, dass die Anmeldedaten und das Registrierungstoken zum selben Firebase-Projekt gehören. Eine Dokumentation zur Authentifizierung der Firebase Admin SDKs finden Sie unter Firebase zu Ihrer App hinzufügen.
messaging/authentication-error Das SDK konnte sich nicht bei den FCM-Servern authentifizieren. Achten Sie darauf, dass Sie die Firebase Admin SDK mit einem Berechtigungsnachweis authentifizieren, der die erforderlichen Berechtigungen zum Senden von FCM-Nachrichten hat. Eine Dokumentation zur Authentifizierung der Firebase Admin SDKs finden Sie unter Firebase zu Ihrer App hinzufügen.
messaging/server-unavailable Der FCM-Server konnte die Anfrage nicht rechtzeitig verarbeiten. Sie sollten dieselbe Anfrage noch einmal senden, aber Sie müssen:
  • Beachten Sie den Retry-After-Header, wenn er in der Antwort vom FCM-Verbindungsserver enthalten ist.
  • Implementieren Sie einen exponentiellen Backoff in Ihrem Wiederholungsmechanismus. Wenn Sie beispielsweise vor dem ersten Wiederholungsversuch eine Sekunde gewartet haben, warten Sie vor dem nächsten mindestens zwei Sekunden, dann vier Sekunden und erhöhen Sie das Sekundenintervall weiter. Wenn Sie mehrere Nachrichten senden, verzögern Sie jede Nachricht unabhängig voneinander um einen zusätzlichen zufälligen Zeitraum, um zu vermeiden, dass für alle Nachrichten gleichzeitig eine neue Anfrage gesendet wird.
Absender, die Probleme verursachen, werden möglicherweise auf die Sperrliste gesetzt.
messaging/internal-error Auf dem FCM-Server ist beim Verarbeiten der Anfrage ein Fehler aufgetreten. Sie können dieselbe Anfrage gemäß den Anforderungen in der vorherigen Zeile messaging/server-unavailable wiederholen. Wenn der Fehler weiterhin auftritt, melden Sie das Problem bitte über unseren Supportkanal Fehlerbericht.
messaging/unknown-error Ein unbekannter Serverfehler wurde 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 Fehlerbericht.