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"
}
]
}
}
Beachten Sie, dass beide Nachrichten denselben Code und Status haben, das Array „details“ jedoch Werte in unterschiedlichen Typen enthält. 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 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 gerichtet ist, dessen Paketname mit dem im Antrag übergebenen Wert übereinstimmt. Message too big (Nachricht zu groß): Achten Sie darauf, dass die Gesamtgröße der Nutzlastdaten in einer Nachricht die FCM-Grenzwerte nicht ü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 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. Das kann beispielsweise auf iOS-Geräten 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 Registrierungstokens 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. 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): 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 eine Überschreitung des Kontingents für die Nachrichtenrate, des Kontingents für die Nachrichtenrate für Geräte oder des Kontingents für die Nachrichtenrate für Themen 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. Device message rate exceeded (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 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, müssen aber Folgendes beachten: – 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, werden möglicherweise auf die Denylisted 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 die Anfrage noch einmal senden und dabei die Vorschläge unter Wiederholungsversuche verarbeiten berücksichtigen oder das FCM-Status-Dashboard prüfen. 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 Nachrichten 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 für
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/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 zum Authentifizieren der Firebase Admin SDKs. |
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 zum Authentifizieren der Firebase Admin SDKs. |
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 noch einmal senden, wenn Sie die Anforderungen erfüllen, die in der vorherigen messaging/server-unavailable-Zeile aufgeführt sind. Wenn der Fehler weiterhin auftritt, melden Sie das Problem bitte über unseren Supportkanal Fehlerbericht.
|
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. |