Kody błędów FCM

Kody błędów REST w interfejsie 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 na błędy:

Przykład 1. Odpowiedź na błąd w żądaniu do interfejsu API HTTP v1 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ź na błąd w żądaniu 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"
      }
    ]
   }
}

Pamiętaj, ż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 czynności wymagane do rozwiązania problemu
UNSPECIFIED_ERROR Brak dodatkowych informacji o tym błędzie.	Brak.
INVALID_ARGUMENT (kod błędu HTTP = 400) Parametry żądania są nieprawidłowe. Zwracana jest rozszerzenie typu google.rpc.BadRequest, aby określić, które pole jest nieprawidłowe.	Możliwe 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 rejestracji przekazywanego do serwera. Upewnij się, że pasuje on do tokena rejestracji, 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. 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ą 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 ttl jest liczbą całkowitą reprezentującą czas trwania w sekundach 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 wyrejestrowanymi tokenami. Brak rejestracji: jeśli celem wiadomości jest wartość token, sprawdź, czy żądanie zawiera token rejestracji. Niezarejestrowany: 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 odinstaluje aplikację. Na przykład w iOS, jeśli usługa opinii APNs zgłosi token APNs jako nieprawidłowy. – jeśli token rejestracji wygaśnie (np. Google może zdecydować się na odświeżenie tokenów rejestracji lub token APNs wygasł na urządzeniach z iOS). – jeśli aplikacja kliencka zostanie 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 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 przejdziesz 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. Zwracana 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ń wiadomości, limitu liczby żądań wiadomości na urządzenie lub limitu liczby żądań wiadomości na temat. Przekroczono limit liczby wiadomości: częstotliwość wysyłania wiadomości jest zbyt wysoka. Musisz zmniejszyć ogólną szybkość 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 wiadomości na urządzenie**: szybkość wysyłania wiadomości na określone 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ć wysyłanie. Przekroczono limit liczby wiadomości na temat: szybkość wysyłania wiadomości do subskrybentów określonego 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ć wysyłanie.
UNAVAILABLE (kod błędu HTTP = 503) Serwer jest przeciążony.	Serwer nie mógł przetworzyć żądania w odpowiednim czasie. Ponów to samo żądanie, ale musisz: - Honor the Retry-After header if it is included in the response from the FCM Connection Server. - Zaimplementuj wzrastający czas do ponowienia w mechanizmie ponawiania. – w mechanizmie ponawiania zaimplementować wzrastający czas do ponowienia (np. jeśli przed pierwszą ponowną próbą odczekasz 1 sekundę, przed następną odczekaj co najmniej 2 sekundy, potem 4 sekundy itd.). Aby uzyskać więcej informacji, zobacz Obsługa ponownych prób, lub sprawdź panel stanu FCM, aby sprawdzić, czy występują zakłócenia w działaniu usługi FCM. Więcej informacji znajdziesz w artykule Obsługa ponownych prób lub sprawdź panel stanu FCM, aby sprawdzić, czy nie występują przerwy w działaniu usługi wpływające na FCM.
INTERNAL (Kod błędu HTTP = 500) Wystąpił nieznany błąd wewnętrzny.	`INTERNAL` (kod błędu HTTP = 500) Wystąpił nieznany błąd wewnętrzny. Podczas próby przetworzenia żądania serwer napotkał błąd. Możesz ponowić to samo żądanie, postępując zgodnie z sugestiami w sekcji Obsługa ponownych prób lub sprawdzając panel stanu FCM. Możesz ponowić to samo żądanie, postępując zgodnie z sugestiami w artykule Obsługa ponownych prób lub sprawdzając panel stanu 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 pusha w internecie jest nieprawidłowy lub brakuje go.	Nie udało się wysłać wiadomości kierowanej na urządzenie z iOS lub rejestracji pusha w internecie. Sprawdź ważność danych uwierzytelniających dewelopera i produkcyjnych.

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 czynności wymagane do 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	Przekazano 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. Ograniczone klucze znajdziesz w dokumentacji referencyjnej DataMessagePayload.
messaging/payload-size-limit-exceeded	Przekazany ł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	Przekazano 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 pasuje on do tokena rejestracji, który aplikacja kliencka otrzymuje podczas rejestracji w FCM. Nie obcinaj tokena ani nie dodawaj do niego dodatkowych 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.: Aplikacja kliencka wyrejestrowała się z FCM. Aplikacja kliencka została automatycznie wyrejestrowana. Może się to zdarzyć, jeśli użytkownik odinstaluje aplikację lub, w przypadku platform Apple, jeśli usługa opinii APNs zgłosi token APNs jako nieprawidłowy. Token rejestracji wygasł. Na przykład Google może zdecydować się na odświeżenie tokenów rejestracji lub token APNs mógł wygasnąć na urządzeniach Apple. Aplikacja kliencka została zaktualizowana, ale nowa wersja nie jest skonfigurowana do odbierania wiadomości. We wszystkich tych przypadkach usuń ten token rejestracji i przestań go używać do wysyłania wiadomości.
messaging/invalid-package-name	Wiadomość została wysłana na token rejestracji, którego nazwa pakietu nie pasuje do podanej opcji restrictedPackageName.
messaging/message-rate-exceeded	Szybkość 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 ponawiaj od razu wysyłania do tego celu.
messaging/device-message-rate-exceeded	Szybkość wysyłania wiadomości na określone urządzenie jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych na to urządzenie i nie ponawiaj od razu wysyłania na to urządzenie.
messaging/topics-message-rate-exceeded	Szybkość wysyłania wiadomości do subskrybentów określonego tematu jest zbyt wysoka. Zmniejsz liczbę wiadomości wysyłanych w tym temacie i nie ponawiaj od razu wysyłania do tego tematu.
messaging/too-many-topics	Token rejestracji został zasubskrybowany do maksymalnej liczby tematów i nie można go zasubskrybować do żadnego innego.
messaging/invalid-apns-credentials	Nie udało się wysłać wiadomości kierowanej 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 uwierzytelniające użyte do uwierzytelnienia tego pakietu SDK nie mają uprawnień do wysyłania wiadomości na urządzenie odpowiadające podanemu tokenowi rejestracji token. Upewnij się, że dane uwierzytelniające i token rejestracji należą do tego samego projektu Firebase. Informacje o tym, jak uwierzytelnić Firebase Admin SDKs, 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 uwierzytelniających, które mają odpowiednie uprawnienia do wysyłania FCM wiadomości. Informacje o tym, jak uwierzytelnić Firebase Admin SDKs, znajdziesz w artykule Dodawanie Firebase do aplikacji.
messaging/server-unavailable	Serwer FCM nie mógł przetworzyć żądania w odpowiednim czasie. 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; w mechanizmie ponawiania zaimplementować wzrastający czas do ponowienia. Na przykład, jeśli przed pierwszą ponowną próbą odczekasz 1 sekundę, przed następną odczekaj co najmniej 2 sekundy, potem 4 sekundy i kontynuuj zwiększanie interwału w sekundach. Jeśli wysyłasz wiele wiadomości, opóźnij każdą z nich o dodatkową losową wartość, aby uniknąć wysyłania nowego żądania dla wszystkich wiadomości w tym samym czasie. Nadawcy, którzy powodują problemy, mogą zostać dodani do listy zablokowanych.
messaging/internal-error	Podczas próby przetworzenia żądania serwer FCM napotkał błąd. Możesz ponowić to samo żądanie, postępując zgodnie z wymaganiami wymienionymi w wierszu messaging/server-unavailable. Jeśli błąd będzie się powtarzał, zgłoś problem, korzystając ze sposobu kontaktu z zespołem pomocy Zgłaszanie błędów.
messaging/unknown-error	Zwrócono nieznany błąd serwera. Więcej informacji znajdziesz w komunikacie o błędzie w postaci nieprzetworzonej odpowiedzi serwera. Jeśli otrzymasz ten błąd, zgłoś pełny komunikat o błędzie w kanale pomocy Zgłaszanie błędów.