Kody błędów REST dla interfejsu HTTP API w wersji 1
Odpowiedzi z błędami HTTP w przypadku interfejsu 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 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 interfejsu HTTP v1 API 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 zaadresowana do tokena rejestracyjnego, którego nazwa pakietu jest zgodna z wartością przekazaną w żądaniu. Zbyt duża wiadomość: 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, 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ą również 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 (kod błędu HTTP = 404) Instancja aplikacji została wyrejestrowana z FCM. Zwykle oznacza to, że używany 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.Niezarejestrowany: 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 APNs Feedback Service 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 (HTTP error code = 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 klienckiej 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 żądań, limitu liczby żądań na urządzenie lub limitu liczby żądań na temat. Przekroczono limit liczby żądań: częstotliwość 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 czasu do ponowienia z minimalnym początkowym opóźnieniem wynoszącym 1 minutę. Przekroczono limit liczby żądań na urządzenie: częstotliwość wysyłania wiadomości na konkretne urządzenie jest zbyt duża. Zapoznaj się z informacjami o limicie 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ć wysyłanie. Przekroczono limit liczby żądań na temat: częstotliwość wysyłania wiadomości do subskrybentów konkretnego tematu jest zbyt duża. Zmniejsz liczbę wiadomości wysyłanych w ramach tego tematu i użyj wzrastającego czasu do ponowienia z minimalnym początkowym opóźnieniem wynoszącym 1 minutę, aby ponowić wysyłanie. |
UNAVAILABLE (kod błędu HTTP = 503) Serwer jest przeciążony. |
Serwer nie zdążył przetworzyć żądania. Spróbuj ponownie, ale musisz: - uwzględnić nagłówek Retry-After, jeśli jest on zawarty w odpowiedzi z serwera połączeń FCM; - w mechanizmie ponawiania zaimplementować wzrastający czas do ponowienia (np. jeśli przed pierwszą próbą ponowienia odczekasz sekundę, przed kolejną odczekaj co najmniej 2 sekundy, potem 4 sekundy itd.). Jeśli wysyłasz wiele wiadomości, rozważ zastosowanie losowego opóźnienia. Więcej informacji znajdziesz w sekcji Obsługa ponawiania. - sprawdź Panel stanu FCM, aby dowiedzieć się, czy występują jakieś bieżące zakłócenia usługi wpływające na FCM. Nadawcy, którzy powodują problemy, mogą zostać umieszczeni na liście odrzuconych. |
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ć to samo żądanie, 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 (HTTP error code = 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 na urządzenie z iOS ani zarejestrować powiadomienia push w internecie. Sprawdź, czy dane logowania w wersji deweloperskiej i produkcyjnej 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, a także zalecane sposoby rozwiązywania problemów.
| Kod błędu | Opis i rozwiązanie |
|---|---|
messaging/invalid-argument |
Do metody 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 dotyczącej
DataMessagePayload.
|
messaging/payload-size-limit-exceeded |
Rozmiar ładunku wiadomości przekracza limit 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 |
Liczba wiadomości wysyłanych do określonego odbiorcy jest zbyt duża. 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. zmniejszyć liczbę wiadomości wysyłanych do tego tematu i nie ponawiać od razu wysyłania do niego. |
messaging/topics-subscription-rate-exceeded |
Częstotliwość żądań zarządzania subskrypcjami dotyczących 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 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 Firebase Admin SDK.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 przesł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ś problem, korzystając z naszego sposobu kontaktu z zespołem pomocy Bug Report.
|
messaging/unknown-error |
Zwrócono nieznany błąd serwera. Więcej szczegółów znajdziesz w surowej odpowiedzi serwera w komunikacie o błędzie. Jeśli otrzymasz ten błąd, zgłoś pełny komunikat o błędzie na naszym sposobie kontaktu z zespołem pomocy Zgłaszanie błędów. |