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. 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. 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.
Zu große Nachricht: Die Gesamtgröße der in einer Nachricht enthaltenen Nutzlastdaten darf die FCM-Limits nicht überschreiten: 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: Die Nutzlastdaten dürfen keinen Schlüssel enthalten, der intern von FCM verwendet wird (z. B. „from“, „gcm“ oder ein Wert mit dem Präfix „google“). 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: Der Wert für „ttl“ muss eine Ganzzahl sein, die eine Dauer in Sekunden zwischen 0 und 2.419.200 (4 Wochen) darstellt.
Ungültige Parameter: Die angegebenen Parameter müssen 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 wenn 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) Die Sendebeschränkung für das Nachrichtenziel wurde überschritten. Eine Erweiterung vom Typ google.rpc.QuotaFailure wird zurückgegeben, um anzugeben, welches Kontingent überschritten wurde. Dieser Fehler kann durch ein überschrittenes Ratenkontingent für Nachrichten, ein überschrittenes Ratenkontingent für Gerätenachrichten oder ein überschrittenes Ratenkontingent für Themennachrichten verursacht werden.
Nachrichtenrate überschritten: Die Versandfrequenz 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 für Geräte ü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 Nachrichten, die an dieses Gerät gesendet werden, und verwenden Sie exponentiellen Backoff, um das Senden noch einmal zu versuchen.
Nachrichtenrate für Themen überschritten: Die Rate der Nachrichten an Abonnenten eines bestimmten Themas ist zu hoch. Reduzieren Sie die Anzahl der Nachrichten, die für dieses Thema gesendet werden, 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. Wiederholen Sie dieselbe Anfrage, aber beachten Sie Folgendes:
- Beachten Sie den Header „Retry-After“, wenn er in der Antwort vom FCM Connection Server 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 Wiederholungen verarbeitenoder im FCM-Status-Dashboard, um festzustellen, 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. Der Server ist beim Versuch, die Anfrage zu verarbeiten, auf einen Fehler gestoßen. Sie können dieselbe Anfrage noch einmal senden und dabei die Vorschläge unter Wiederholungen verarbeiten befolgen oder im FCM-Status-Dashboard nachsehen. ob es laufende 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 Nachrichtennutzlastobjekt angegeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-data-payload-key Die Nutzlast der Datennachricht enthält einen ungültigen Schlüssel. Informationen zu eingeschränkten Schlüsseln finden Sie in der Referenzdokumentation für DataMessagePayload.
messaging/payload-size-limit-exceeded Die angegebene Nachrichtennutzlast ü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 Nachrichtenoptionsobjekt angegeben. Die Fehlermeldung sollte zusätzliche Informationen enthalten.
messaging/invalid-registration-token Es wurde ein ungültiges Registrierungstoken angegeben. 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, auf Apple-Plattformen, wenn der APNs Feedback Service 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 Nachrichten, die an dieses Gerät oder Thema gesendet werden, und versuchen Sie nicht sofort, das Senden an dieses Ziel zu wiederholen.
messaging/device-message-rate-exceeded Die Rate der Nachrichten an ein bestimmtes Gerät ist zu hoch. Reduzieren Sie die Anzahl der Nachrichten, die an dieses Gerät gesendet werden, und versuchen Sie nicht sofort, das Senden an dieses Gerät zu wiederholen.
messaging/topics-message-rate-exceeded Die Rate der Nachrichten an Abonnenten eines bestimmten Themas ist zu hoch. Reduzieren Sie die Anzahl der Nachrichten, die für dieses Thema gesendet werden, und versuchen Sie nicht sofort, das Senden an dieses Thema zu wiederholen.
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 Entwicklungs- und Produktionszertifikate.
messaging/mismatched-credential Die Anmeldedaten, die zur Authentifizierung dieses SDK verwendet werden, 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. Authentifizieren Sie das Firebase Admin SDK mit Anmeldedaten, 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. Sie sollten dieselbe Anfrage noch einmal senden, aber beachten Sie Folgendes:
  • Beachten Sie den Retry-After Header, wenn er in der Antwort vom FCM Connection Server 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 Zufallsbetrag, 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 Der FCM Server ist beim Versuch, die Anfrage zu verarbeiten, auf einen Fehler gestoßen. Sie können dieselbe Anfrage noch einmal senden und dabei die Anforderungen in der vorherigen messaging/server-unavailable Zeile befolgen. 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.