Kody błędów REST dla interfejsu HTTP v1 API
Odpowiedzi na błędy HTTP w interfejsie HTTP v1 API zawierają kod błędu, komunikat o błędzie i stan błędu. Mogą też zawierać tablicę details z dodatkowymi informacjami o błędzie.
Oto 2 przykładowe odpowiedzi z błędem:
Przykład 1. Odpowiedź z błędem na żądanie do interfejsu HTTP v1 API z nieprawidłową wartością w wiadomości z danymi
{
"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"
}
]
}
]
}
}
Przykład 2. Odpowiedź z błędem na żądanie do interfejsu API HTTP v1 z nieprawidłowym tokenem rejestracji
{
"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"
}
]
}
}
Zwróć uwagę, że obie wiadomości mają ten sam kod i stan, ale tablica szczegółów zawiera wartości różnych typów. Pierwszy przykład ma typ type.googleapis.com/google.rpc.BadRequest, co oznacza błąd w wartościach żądania. Drugi przykład z typem type.googleapis.com/google.firebase.fcm.v1.FcmError zawiera błąd związany z FCM.
W przypadku wielu błędów tablica szczegółów zawiera informacje potrzebne do debugowania i znalezienia rozwiązania.
W tabeli poniżej znajdziesz kody błędów interfejsu FCM v1 REST API i ich opisy.
| Kod błędu | Opis i czynności wymagane do rozwiązania problemu |
|---|---|
UNSPECIFIED_ERROR Nie ma więcej informacji o tym błędzie. |
Brak. |
INVALID_ARGUMENT (kod błędu HTTP = 400) Parametry żądania były nieprawidłowe. Zwracane jest rozszerzenie typu google.rpc.BadRequest, które wskazuje, które pole było nieprawidłowe. |
Potencjalne przyczyny to nieprawidłowa rejestracja, nieprawidłowa nazwa pakietu, zbyt duża wiadomość, nieprawidłowy klucz danych, nieprawidłowy czas TTL lub inne nieprawidłowe parametry. Nieprawidłowa rejestracja: sprawdź format tokena rejestracji przekazywanego do serwera. Upewnij się, że jest on zgodny z tokenem rejestracji, który aplikacja kliencka otrzymuje po zarejestrowaniu się w FCM. Nie skracaj tokena ani nie dodawaj do niego znaków. Nieprawidłowa nazwa pakietu: upewnij się, że wiadomość została zaadresowana do tokena rejestracji, którego nazwa pakietu jest zgodna z wartością przekazaną w żądaniu. Wiadomość jest za duża: sprawdź, czy łączny rozmiar danych ładunku zawartych w wiadomości nie przekracza limitów FCM: 4096 bajtów w przypadku większości wiadomości lub 2048 bajtów w przypadku wiadomości do tematów. Obejmuje to zarówno klucze, jak i wartości. Nieprawidłowy klucz danych: sprawdź, czy dane ładunku nie zawierają klucza (np. from lub gcm albo dowolnej wartości z prefiksem google) używanego wewnętrznie przez FCM. Pamiętaj, że niektóre słowa (np. collapse_key) są też używane przez FCM, ale są dozwolone w ładunku. W takim przypadku wartość ładunku zostanie zastąpiona wartością FCM. Nieprawidłowy TTL: sprawdź, czy wartość użyta w ttl jest liczbą całkowitą reprezentującą czas trwania w sekundach z zakresu od 0 do 2 419 200 (4 tygodnie). Nieprawidłowe parametry: sprawdź, czy podane parametry mają prawidłową nazwę i typ. |
UNREGISTERED (kod błędu HTTP = 404) Instancja aplikacji została wyrejestrowana z FCM. Zwykle oznacza to, że użyty token nie jest już ważny i należy użyć nowego. |
Ten błąd może być spowodowany brakiem tokenów rejestracji lub niezarejestrowanymi tokenami. Missing Registration: jeśli elementem docelowym wiadomości jest wartość token, sprawdź, czy żądanie zawiera token rejestracji.Not registered: istniejący token rejestracji może przestać być ważny w kilku sytuacjach, m.in.: – jeśli aplikacja kliencka wyrejestruje się z FCM, – jeśli aplikacja kliencka zostanie automatycznie wyrejestrowana, co może się zdarzyć, gdy użytkownik ją odinstaluje. Na przykład w systemie iOS, jeśli usługa APNs Feedback Service zgłosiła token APNs jako nieprawidłowy. – token rejestracji wygasa (na przykład Google może zdecydować o odświeżeniu tokenów rejestracji lub token APNs wygasł na urządzeniach z iOS). – jeśli aplikacja kliencka została zaktualizowana, ale nowa wersja nie jest skonfigurowana do odbierania wiadomości. We wszystkich tych przypadkach usuń token rejestracji z serwera aplikacji i przestań go używać do wysyłania wiadomości. |
SENDER_ID_MISMATCH (kod błędu HTTP = 403) Uwierzytelniony identyfikator nadawcy różni się od identyfikatora nadawcy tokena rejestracji. |
Token rejestracji jest powiązany z określoną grupą nadawców. Gdy aplikacja kliencka rejestruje się w FCM, musi określić, którzy nadawcy mogą wysyłać wiadomości. Podczas wysyłania wiadomości do aplikacji klienckiej należy użyć jednego z tych identyfikatorów nadawcy. Jeśli przełączysz się na innego nadawcę, dotychczasowe tokeny rejestracji nie będą działać. |
QUOTA_EXCEEDED (kod błędu HTTP = 429) Przekroczono limit wysyłania dla celu wiadomości. Zwracane jest rozszerzenie typu google.rpc.QuotaFailure, które określa, który limit został przekroczony. |
Ten błąd może być spowodowany przekroczeniem limitu liczby żądań wiadomości, przekroczeniem limitu liczby żądań wiadomości na urządzenie lub przekroczeniem limitu liczby żądań wiadomości na temat. Przekroczono częstotliwość wysyłania wiadomości: częstotliwość wysyłania wiadomości jest zbyt wysoka. Musisz zmniejszyć ogólną częstotliwość wysyłania wiadomości. Aby ponowić próbę wysłania odrzuconych wiadomości, użyj wzrastającego czasu do ponowienia z minimalnym początkowym opóźnieniem wynoszącym 1 minutę. Przekroczono częstotliwość wysyłania wiadomości na urządzenie: częstotliwość wysyłania wiadomości na konkretne urządzenie jest zbyt wysoka. Zobacz limit liczby wiadomości na jedno urządzenie. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i użyj wzrastającego czasu do ponowienia, aby ponowić próbę wysłania. Przekroczono częstotliwość wiadomości na dany temat: częstotliwość wysyłania wiadomości do subskrybentów danego tematu jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych w tym temacie i użyj wzrastającego czasu do ponowienia z minimalnym początkowym opóźnieniem wynoszącym 1 minutę, aby ponowić próbę wysłania. |
UNAVAILABLE (kod błędu HTTP = 503) Serwer jest przeciążony. |
Serwer nie mógł przetworzyć żądania na czas. Ponów to samo żądanie, ale musisz: – uwzględnić nagłówek Retry-After, jeśli jest on zawarty w odpowiedzi z serwera połączeń FCM. – Zaimplementuj wzrastający czas do ponowienia w mechanizmie ponawiania prób. (np.jeśli przed pierwszą próbą odczekasz sekundę, przed następną odczekaj co najmniej 2 sekundy, potem 4 sekundy itd.). Jeśli wysyłasz wiele wiadomości, rozważ zastosowanie jitteringu. Więcej informacji znajdziesz w artykule Obsługa ponownych prób. Możesz też sprawdzić panel stanu FCM, aby dowiedzieć się, czy nie występują przerwy w działaniu usługi, które wpływają na FCM. Nadawcy, którzy powodują problemy, mogą zostać dodani do listy odrzuconych. |
INTERNAL (kod błędu HTTP = 500) Wystąpił nieznany błąd wewnętrzny. |
Podczas próby przetworzenia żądania serwer napotkał błąd. Możesz spróbować ponownie wysłać to samo żądanie, postępując zgodnie z sugestiami podanymi w sekcji Obsługa ponownych prób lub sprawdzając panel stanu FCM. aby sprawdzić, czy nie występują przerwy w działaniu usługi FCM. Jeśli błąd będzie się powtarzał, skontaktuj się z zespołem pomocy Firebase. |
THIRD_PARTY_AUTH_ERROR (kod błędu HTTP = 401) Certyfikat APNs lub klucz uwierzytelniania powiadomień push w internecie był nieprawidłowy lub go brakowało. |
Nie udało się wysłać wiadomości kierowanej na urządzenie z iOS lub rejestracji powiadomień push w internecie. Sprawdź, czy dane logowania do środowiska programistycznego i produkcyjnego są prawidłowe. |
Kody błędów pakietu Admin SDK
W tabeli poniżej znajdziesz kody błędów interfejsu Firebase Admin FCM API i ich opisy, w tym zalecane sposoby rozwiązania problemu.
| Kod błędu | Opis i czynności wymagane do rozwiązania problemu |
|---|---|
messaging/invalid-argument |
Do metody FCM przekazano nieprawidłowy argument. Komunikat o błędzie powinien zawierać dodatkowe informacje. |
messaging/invalid-recipient |
Odbiorca wiadomości jest nieprawidłowy. Komunikat o błędzie powinien zawierać dodatkowe informacje. |
messaging/invalid-payload |
Podano nieprawidłowy obiekt ładunku wiadomości. Komunikat o błędzie powinien zawierać dodatkowe informacje. |
messaging/invalid-data-payload-key |
Ładunek wiadomości z danymi zawiera nieprawidłowy klucz. Informacje o ograniczonych klawiszach znajdziesz w dokumentacji
DataMessagePayload.
|
messaging/payload-size-limit-exceeded |
Podany ładunek wiadomości przekracza limity rozmiaru FCM. W przypadku większości wiadomości limit wynosi 4096 bajtów. W przypadku wiadomości wysyłanych do tematów limit wynosi 2048 bajtów. Łączny rozmiar ładunku obejmuje zarówno klucze, jak i wartości. |
messaging/invalid-options |
Podano nieprawidłowy obiekt opcji wiadomości. Komunikat o błędzie powinien zawierać dodatkowe informacje. |
messaging/invalid-registration-token |
Podano nieprawidłowy token rejestracji. Upewnij się, że jest on zgodny z tokenem rejestracji, który aplikacja kliencka otrzymuje po zarejestrowaniu się w FCM. Nie skracaj go ani nie dodawaj do niego znaków. |
messaging/registration-token-not-registered |
Podany token rejestracji nie jest zarejestrowany. Wcześniej prawidłowy token rejestracji może zostać wyrejestrowany z różnych powodów, m.in.:
|
messaging/invalid-package-name |
Wiadomość została zaadresowana do tokena rejestracji, którego nazwa pakietu nie pasuje do podanej opcji
restrictedPackageName.
|
messaging/message-rate-exceeded |
Częstotliwość wysyłania wiadomości do określonego celu jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie lub do tego tematu i nie próbuj od razu wysyłać ich ponownie. |
messaging/device-message-rate-exceeded |
Częstotliwość wysyłania wiadomości na określone urządzenie jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i nie próbuj od razu wysyłać ich ponownie. |
messaging/topics-message-rate-exceeded |
Liczba wiadomości wysyłanych do subskrybentów danego tematu jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych do tego tematu i nie próbuj od razu wysyłać ich ponownie. |
messaging/topics-subscription-rate-exceeded |
Częstotliwość żądań zarządzania subskrypcjami w przypadku określonego tematu jest zbyt wysoka. Zmniejsz liczbę żądań wysyłanych w przypadku tego tematu i nie ponawiaj od razu żądania. |
messaging/too-many-topics |
Token rejestracji został zasubskrybowany do maksymalnej liczby tematów i nie można go zasubskrybować do kolejnych. |
messaging/invalid-apns-credentials |
Nie udało się wysłać wiadomości na urządzenie Apple, ponieważ wymagany certyfikat SSL APNs nie został przesłany lub wygasł. Sprawdź ważność certyfikatów programistycznych i produkcyjnych. |
messaging/mismatched-credential |
Dane logowania używane do uwierzytelniania tego pakietu SDK nie mają uprawnień do wysyłania wiadomości na urządzenie odpowiadające podanemu tokenowi rejestracji. Upewnij się, że dane logowania i token rejestracji należą do tego samego projektu w Firebase. Dokumentację dotyczącą uwierzytelniania Firebase Admin SDK znajdziesz w artykule Dodawanie Firebase do aplikacji. |
messaging/authentication-error |
Pakiet SDK nie mógł uwierzytelnić się na serwerach FCM. Upewnij się, że uwierzytelniasz Firebase Admin SDK za pomocą danych logowania, które mają odpowiednie uprawnienia do wysyłania wiadomości FCM. Dokumentację dotyczącą uwierzytelniania Firebase Admin SDKs znajdziesz w artykule Dodawanie Firebase do aplikacji. |
messaging/server-unavailable |
Serwer FCM nie mógł przetworzyć żądania na czas. Spróbuj ponownie wysłać to samo żądanie, ale:
|
messaging/internal-error |
Podczas próby przetworzenia żądania na serwerze FCM wystąpił błąd. Możesz spróbować ponownie wysłać to samo żądanie, spełniając wymagania wymienione we wcześniejszym wierszu messaging/server-unavailable. Jeśli błąd będzie się powtarzał, zgłoś go w raporcie o błędzie, korzystając ze sposobu kontaktu z zespołem pomocy.
|
messaging/unknown-error |
Wystąpił nieznany błąd serwera. Więcej informacji znajdziesz w komunikacie o błędzie zawierającym nieprzetworzoną odpowiedź serwera. Jeśli pojawi się ten błąd, zgłoś pełny komunikat o błędzie w naszym kanale pomocy Zgłoś błąd. |