Kody błędów REST dla interfejsu HTTP API w wersji 1
Odpowiedzi z błędami HTTP w przypadku interfejsu HTTP API w wersji 1 zawierają kod błędu, komunikat o błędzie i stan błędu. Mogą też zawierać details tablicę 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 API w wersji 1 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ź o błędzie z żądania do interfejsu HTTP API w wersji 1 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 oba komunikaty 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 specyficzny dla 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 rozwiązanie |
|---|---|
UNSPECIFIED_ERROR Nie mamy 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, aby określić, 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łowa wartość TTL lub inne nieprawidłowe parametry. Nieprawidłowa rejestracja: sprawdź format tokena rejestracyjnego przekazywanego na serwer. Upewnij się, że jest on zgodny z tokenem rejestracyjnym, który aplikacja kliencka otrzymuje podczas rejestracji w FCM. Nie obcinaj tokena ani nie dodawaj do niego dodatkowych znaków. Nieprawidłowa nazwa pakietu: upewnij się, że wiadomość została wysłana na token 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. Dotyczy to zarówno kluczy, jak i wartości. Nieprawidłowy klucz danych: sprawdź, czy dane w ładunku nie zawierają klucza (np. from, gcm lub dowolnej wartości z prefiksem google), który jest używany 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łowa wartość TTL: sprawdź, czy wartość użyta w parametrze 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 (HTTP error code = 404) Instancja aplikacji została wyrejestrowana z FCM. Zwykle oznacza to, że użyty token jest już nieważny i trzeba użyć nowego. |
Ten błąd może być spowodowany brakiem tokenów rejestracji lub niezarejestrowanymi tokenami. Brak rejestracji: jeśli elementem docelowym wiadomości jest wartość token, sprawdź, czy żądanie zawiera token rejestracji.Nie zarejestrowano: istniejący token rejestracji może przestać być ważny w wielu sytuacjach, m.in.: – gdy aplikacja kliencka wyrejestruje się z FCM. – jeśli aplikacja kliencka zostanie automatycznie wyrejestrowana, co może się zdarzyć, gdy użytkownik odinstaluje aplikację. Na przykład w systemie iOS, jeśli usługa informacji zwrotnych APNs zgłosiła, że token APNs jest nieprawidłowy. – jeśli token rejestracji wygaśnie (np. Google może odświeżyć tokeny rejestracji lub token APNs wygasł na urządzeniach z iOS). – jeśli aplikacja klienta została zaktualizowana, ale nowa wersja nie jest skonfigurowana do odbierania wiadomości. We wszystkich tych przypadkach usuń ten 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 dla 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 klienta używaj jednego z tych identyfikatorów nadawcy. Jeśli zmienisz nadawcę, dotychczasowe tokeny rejestracji przestaną działać. |
QUOTA_EXCEEDED (kod błędu HTTP = 429) Przekroczono limit wysyłania do miejsca docelowego wiadomości. Zwracane jest rozszerzenie typu google.rpc.QuotaFailure, aby określić, który limit został przekroczony. |
Ten błąd może być spowodowany przekroczeniem limitu liczby wiadomości, limitu liczby wiadomości na urządzenie lub limitu liczby wiadomości na temat. Przekroczono limit wysyłania wiadomości: szybkość wysyłania wiadomości jest zbyt duża. Musisz zmniejszyć ogólną częstotliwość wysyłania wiadomości. Aby ponowić wysyłanie odrzuconych wiadomości, użyj wzrastającego wykładniczo 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 określone urządzenie jest zbyt wysoka. Zobacz limit liczby wiadomości wysyłanych na 1 urządzenie. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i używaj strategii wzrastającego czasu do ponowienia, aby ponownie spróbować wysłać wiadomość. Przekroczono liczbę wiadomości w temacie: liczba wiadomości wysyłanych do subskrybentów danego tematu jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych w tym temacie i używaj rosnącego wykładniczo czasu do ponowienia z minimalnym początkowym opóźnieniem wynoszącym 1 minutę. |
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. – Wdróż w mechanizmie ponawiania wzrastający czas do ponowienia. (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 występują przerwy w działaniu usługi FCM. Nadawcy, którzy powodują problemy, mogą zostać umieszczeni na liście zablokowanych. |
INTERNAL (HTTP error code = 500) Wystąpił nieznany błąd wewnętrzny. |
Podczas próby przetworzenia żądania serwer napotkał błąd. Możesz ponownie wysłać tę samą prośbę, postępując zgodnie z sugestiami w sekcji Obsługa ponownych prób lub sprawdzając panel stanu FCM. aby sprawdzić, czy nie występują bieżące przerwy w działaniu usługi wpływające na 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 autoryzacji powiadomień push w internecie był nieprawidłowy lub brakowało go. |
Nie udało się wysłać wiadomości kierowanej na urządzenie z iOS ani rejestracji powiadomień push w internecie. Sprawdź poprawność danych logowania do środowiska deweloperskiego i produkcyjnego. |
Kody błędów pakietu Admin SDK
W tabeli poniżej znajdziesz kody błędów interfejsu Firebase Admin FCM API i ich opisy, a także zalecane działania.
| Kod błędu | Opis i rozwiązanie |
|---|---|
messaging/invalid-argument |
W metodzie FCM podano 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 kluczach z ograniczeniami znajdziesz w dokumentacji referencyjnej
DataMessagePayload.
|
messaging/payload-size-limit-exceeded |
Podany ładunek wiadomości przekracza limit 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 podczas rejestracji w usłudze FCM. Nie obcinaj ani nie dodawaj do niego dodatkowych znaków. |
messaging/registration-token-not-registered |
Podany token rejestracji nie jest zarejestrowany. Wcześniej prawidłowy token rejestracyjny może zostać wyrejestrowany z różnych powodów, m.in.:
|
messaging/invalid-package-name |
Wiadomość została wysłana na token rejestracyjny, którego nazwa pakietu nie pasuje do podanej opcji
restrictedPackageName.
|
messaging/message-rate-exceeded |
Częstotliwość wysyłania wiadomości do określonego odbiorcy jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie lub do tego tematu i nie próbuj od razu ponownie wysłać wiadomości do tego miejsca docelowego. |
messaging/device-message-rate-exceeded |
Częstotliwość wysyłania wiadomości na konkretne urządzenie jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i nie próbuj od razu ponownie wysyłać wiadomości na to urządzenie. |
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 ponownie wysyłać wiadomości do tego tematu. |
messaging/too-many-topics |
Token rejestracji został zasubskrybowany w maksymalnej liczbie tematów i nie można go zasubskrybować w żadnym innym. |
messaging/invalid-apns-credentials |
Nie można wysłać wiadomości na urządzenie Apple, ponieważ wymagany certyfikat SSL APNs nie został przesłany lub wygasł. Sprawdź ważność certyfikatów deweloperskich i produkcyjnych. |
messaging/mismatched-credential |
Dane logowania użyte do uwierzytelnienia 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 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 SDK znajdziesz w artykule Dodawanie Firebase do aplikacji. |
messaging/server-unavailable |
Serwer FCM nie mógł przetworzyć żądania na czas. Powtórz to samo żądanie, ale musisz:
|
messaging/internal-error |
Serwer FCM napotkał błąd podczas próby przetworzenia żądania. Możesz ponownie wysłać to samo żądanie, postępując zgodnie z wymaganiami podanymi w wierszu messaging/server-unavailable. Jeśli błąd będzie się powtarzał, zgłoś go na naszym kanale pomocy Bug Report.
|
messaging/unknown-error |
Wystąpił nieznany błąd serwera. Więcej informacji znajdziesz w komunikacie o błędzie, który zawiera nieprzetworzoną odpowiedź serwera. Jeśli pojawi się ten błąd, zgłoś pełny komunikat o błędzie na naszym kanale pomocy Raport o błędach. |