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 Nachrichten haben denselben Code und Status, aber das Detail-Array enthält Werte in verschiedenen Typen. Das erste Beispiel hat den Typ type.googleapis.com/google.rpc.BadRequest, was auf einen Fehler bei den Anforderungswerten 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 Detail-Array 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. 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: Achten Sie darauf, dass die Nachricht an ein Registrierungstoken adressiert wurde, dessen Paketname mit dem in der Anfrage ü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“, „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 verschiedenen Szenarien ungültig werden, z. B.: – Wenn die Client-App die Registrierung bei FCM aufhebt. – Wenn die Registrierung der Client-App automatisch aufgehoben wird. Das kann passieren, wenn der Nutzer die Anwendung deinstalliert. Auf iOS-Geräten kann das z. B. der Fall sein, wenn der APNs-Feedbackdienst das APNs-Token als ungültig gemeldet hat. – Wenn das Registrierungstoken abläuft. Google kann z. B. Registrierungstokens aktualisieren oder das APNs-Token für iOS-Geräte ist abgelaufen. – 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 das 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 allgemeine Rate, mit der Sie Nachrichten senden, reduzieren. Verwenden Sie für abgelehnte Nachrichten einen exponentiellen Backoff mit einer anfänglichen Mindestverzögerung von 1 Minute. Gerätenachrichtenrate überschritten: Die Rate der Nachrichten an ein bestimmtes Gerät ist zu hoch. Weitere Informationen Reduzieren Sie die Anzahl der Nachrichten, die an dieses Gerät gesendet werden, und verwenden Sie exponentielles 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 einen 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: – Wenn der Header „Retry-After“ in der Antwort des FCM-Verbindungsservers enthalten ist, müssen Sie ihn berücksichtigen. – Implementieren Sie den 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 Wiederholungsversuche verarbeiten. Im FCM-Status-Dashboard können Sie nachsehen, ob es aktuelle 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. |
Beim Versuch, die Anfrage zu verarbeiten, ist auf dem Server ein Fehler aufgetreten. Sie können die Anfrage noch einmal senden. Folgen Sie dazu den Vorschlägen unter Wiederholungsversuche 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 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 |
Für eine FCM-Methode wurde ein ungültiges Argument angegeben. 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 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 Bytes. 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 |
Es wurde ein 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 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.:
|
messaging/invalid-package-name |
Die Nachricht wurde an ein Registrierungstoken adressiert, 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, Nachrichten 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 Nachrichten, die für dieses Thema gesendet werden, und versuchen Sie nicht sofort, Nachrichten an dieses Thema zu senden. |
messaging/topics-subscription-rate-exceeded |
Die Anzahl der Anfragen zur Aboverwaltung für ein bestimmtes 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 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 Anmeldedaten, die zur Authentifizierung dieses SDK verwendet werden, haben 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. Unter Firebase zu Ihrer App hinzufügen finden Sie eine Anleitung dazu, wie Sie die Firebase Admin SDK authentifizieren. |
messaging/authentication-error |
Das SDK konnte sich nicht bei den FCM-Servern authentifizieren. Achten Sie darauf, dass Sie die Firebase Admin SDK mit einem Anmeldedatenpaar authentifizieren, das die erforderlichen Berechtigungen zum Senden von FCM-Nachrichten hat. Unter Firebase zu Ihrer App hinzufügen finden Sie eine Anleitung dazu, wie Sie die Firebase Admin SDK authentifizieren. |
messaging/server-unavailable |
Der FCM-Server konnte die Anfrage nicht rechtzeitig verarbeiten. Sie sollten die Anfrage noch einmal senden, müssen aber Folgendes beachten:
|
messaging/internal-error |
Auf dem FCM-Server ist beim Versuch, die Anfrage zu verarbeiten, ein Fehler aufgetreten. Sie können die Anfrage unter Einhaltung der Anforderungen in der vorherigen messaging/server-unavailable-Zeile noch einmal senden. 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 sie bitte über unseren Supportkanal Fehlerbericht. |