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 auf eine 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 auf eine 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 Meldungen haben denselben Code und Status, aber das Array „details“ enthält Werte in unterschiedlichen Typen. Das erste Beispiel hat den Typ type.googleapis.com/google.rpc.BadRequest, was auf einen Fehler in den Anforderungswerten 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 zum Debuggen und zur Fehlerbehebung 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 Zu diesem Fehler sind keine weiteren Informationen 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 unter anderem 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 Clientanwendung 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 im Antrag übergebenen Wert übereinstimmt.
Nachricht zu groß: Prüfen Sie, ob die Gesamtgröße der Nutzlastdaten in einer Nachricht die FCM-Grenzwerte überschreitet: 4.096 Byte für die meisten Nachrichten oder 2.048 Byte für Nachrichten an Themen. Das 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“ oder „gcm“ oder ein beliebiger Wert mit dem Präfix „google“. Einige Wörter wie „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: Prüfen Sie,ob 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 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 einer Reihe von 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. Auf iOS-Geräten beispielsweise, wenn der APNs-Feedbackdienst das APNs-Token als ungültig gemeldet hat.
– Wenn das Registrierungstoken abläuft (z. B. wenn Google Registrierungstokens aktualisiert oder das APNs-Token für iOS-Geräte abgelaufen ist).
– Wenn die Client-App aktualisiert wurde, 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. 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): Die Sendebeschränkung 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 eine Überschreitung des Ratenkontingents für Nachrichten, des Ratenkontingents für Gerätenachrichten oder des Ratenkontingents für Themennachrichten verursacht werden.
Nachrichtenfrequenz überschritten: Die Sendefrequenz von Nachrichten ist zu hoch. Sie müssen die Gesamtrate, mit der Sie Nachrichten senden, verringern. Verwenden Sie den exponentiellen Backoff mit einer anfänglichen Mindestverzögerung von einer Minute, um abgelehnte Nachrichten noch einmal zu senden.
Gerätenachrichtenfrequenz überschritten: Die Frequenz der Nachrichten an ein bestimmtes Gerät ist zu hoch. Weitere Informationen zum Nachrichtenratenlimit für ein einzelnes Gerät Reduzieren Sie die Anzahl der Nachrichten, die an dieses Gerät gesendet werden, und verwenden Sie den exponentiellen Backoff, um das Senden zu wiederholen.
Nachrichtenrate für 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 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:
– Wenn der FCM-Verbindungsserver den Header „Retry-After“ in die Antwort aufnimmt, müssen Sie ihn berücksichtigen.
– Implementieren Sie exponentiellen Backoff in Ihrem Wiederholungsmechanismus. Wenn Sie beispielsweise eine Sekunde vor dem ersten Wiederholungsversuch 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 Wiederholungsversuche verarbeiten. Sie können auch das FCM-Status-Dashboard aufrufen, um festzustellen, ob es laufende Dienstunterbrechungen gibt, die sich auf FCM auswirken. Absender, die Probleme verursachen, riskieren, auf die Denylist gesetzt zu werden.
INTERNAL (HTTP-Fehlercode = 500) Ein unbekannter interner Fehler ist aufgetreten. Auf dem Server ist bei dem Versuch, die Anfrage zu verarbeiten, ein Fehler aufgetreten. Sie können den gleichen Antrag noch einmal stellen und dabei die Vorschläge unter Wiederholungsversuche verarbeiten FCM-Status-Dashboard beachten. 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 für ein iOS-Gerät oder eine Web-Push-Registrierung bestimmt 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 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 angegeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-data-payload-key Die Nutzlast der Datenmitteilung 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, gilt ein Limit von 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 Clientanwendung bei der Registrierung bei FCM erhält. Kürzen Sie den Namen 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 selbst von FCM abgemeldet.
  • Die Client-App wurde automatisch abgemeldet. Das kann passieren, wenn der Nutzer die Anwendung deinstalliert oder, auf Apple-Plattformen, wenn der APNs-Feedbackdienst das APNs-Token als ungültig gemeldet hat.
  • Das Registrierungstoken ist abgelaufen. Google kann beispielsweise Registrierungstokens 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 gesendet, dessen Paketname nicht mit der angegebenen Option restrictedPackageName übereinstimmt.
messaging/message-rate-exceeded Die Anzahl 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 Nachrichten noch einmal an dieses Ziel zu senden.
messaging/device-message-rate-exceeded Die Anzahl der Nachrichten an ein bestimmtes Gerät ist zu hoch. Reduziere die Anzahl der Nachrichten, die an dieses Gerät gesendet werden, und versuche nicht sofort, Nachrichten an dieses Gerät zu senden.
messaging/topics-message-rate-exceeded Die Anzahl der Nachrichten, die an Abonnenten eines bestimmten Themas gesendet werden, 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 Anzahl der Anfragen zur Aboverwaltung zu einem bestimmten Thema ist zu hoch. Reduzieren Sie die Anzahl der für dieses Thema gesendeten Anfragen und versuchen Sie es nicht sofort noch einmal.
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 für ein Apple-Gerät bestimmt war, konnte nicht gesendet werden, da das erforderliche APNs-SSL-Zertifikat nicht hochgeladen wurde oder abgelaufen ist. Prüfen Sie die Gültigkeit Ihrer Entwicklungs- und Produktionszertifikate.
messaging/mismatched-credential Der Berechtigungsnachweis, der zur Authentifizierung dieses SDK verwendet wird, hat keine Berechtigung zum Senden von Nachrichten an das Gerät, das dem angegebenen Registrierungstoken entspricht. Das Anmeldedaten- und das Registrierungstoken müssen zum selben Firebase-Projekt gehören. Informationen zum Authentifizieren der Firebase Admin SDKs finden Sie unter Firebase in Ihre App einbinden.
messaging/authentication-error Das SDK konnte sich nicht bei den FCM-Servern authentifizieren. Achten Sie darauf, dass Sie die Firebase Admin SDK mit einem Anmeldedatum authentifizieren, das die erforderlichen Berechtigungen zum Senden von FCM-Nachrichten hat. Informationen zum Authentifizieren der Firebase Admin SDKs finden Sie unter Firebase in Ihre App einbinden.
messaging/server-unavailable Der FCM-Server konnte die Anfrage nicht rechtzeitig verarbeiten. Sie sollten die Anfrage noch einmal senden, müssen dabei aber Folgendes beachten:
  • Berücksichtigen 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 eine Sekunde vor dem ersten Wiederholungsversuch gewartet haben, warten Sie mindestens zwei Sekunden vor dem nächsten, dann vier Sekunden und so weiter. Wenn Sie mehrere Nachrichten senden, verzögern Sie jede Nachricht unabhängig um einen zusätzlichen zufälligen Betrag, um zu vermeiden, dass für alle Nachrichten gleichzeitig eine neue Anfrage gestellt wird.
Absender, die Probleme verursachen, riskieren, auf die Blockierliste gesetzt zu werden.
messaging/internal-error Auf dem FCM-Server ist beim Verarbeiten der Anfrage ein Fehler aufgetreten. Sie können dieselbe Anfrage noch einmal senden und dabei die Anforderungen aus der vorherigen Zeile messaging/server-unavailable beachten. Wenn der Fehler weiterhin auftritt, melden Sie das Problem bitte über unseren Supportkanal Fehler melden.
messaging/unknown-error Es wurde ein unbekannter Serverfehler zurückgegeben. Weitere Informationen finden Sie in der Rohantwort des Servers in der Fehlermeldung. Wenn Sie diese Fehlermeldung erhalten, melden Sie die vollständige Fehlermeldung bitte über den Supportkanal Fehler melden.