Codici di errore FCM

Codici di errore REST per l'API HTTP v1

Le risposte di errore HTTP per l'API HTTP v1 contengono un codice di errore, un messaggio di errore e uno stato di errore. Potrebbero anche contenere un array details con ulteriori dettagli sull'errore.

Ecco due esempi di risposte di errore:

Esempio 1: risposta di errore da una richiesta API HTTP v1 con un valore non valido in un messaggio di dati

{
  "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"
          }
        ]
      }
    ]
  }
}

Esempio 2: risposta di errore da una richiesta API HTTP v1 con un token di registrazione non valido

{
  "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"
      }
    ]
   }
}

Tieni presente che entrambi i messaggi hanno lo stesso codice e lo stesso stato, ma l'array dei dettagli contiene valori di tipi diversi. Il primo esempio ha il tipo type.googleapis.com/google.rpc.BadRequest, che indica un errore nei valori della richiesta. Il secondo esempio con tipo type.googleapis.com/google.firebase.fcm.v1.FcmError presenta un errore specifico di FCM. Per molti errori, l'array details contiene le informazioni necessarie per eseguire il debug e trovare una soluzione.

La tabella seguente elenca i codici di errore dell'API REST FCM v1 e le relative descrizioni.

Codice di errore Descrizione e passaggi per la risoluzione
UNSPECIFIED_ERROR Non sono disponibili ulteriori informazioni su questo errore. Nessuno.
INVALID_ARGUMENT (codice di errore HTTP = 400) I parametri della richiesta non erano validi. Viene restituita un'estensione di tipo google.rpc.BadRequest per specificare quale campo non è valido. Le cause potenziali includono registrazione non valida, nome del pacchetto non valido, messaggio troppo grande, chiave dati non valida, TTL non valido o altri parametri non validi.
Registrazione non valida: controlla il formato del token di registrazione che passi al server. Assicurati che corrisponda al token di registrazione che l'app client riceve dalla registrazione con FCM. Non troncare il token e non aggiungere altri caratteri.
Nome del pacchetto non valido: assicurati che il messaggio sia stato indirizzato a un token di registrazione il cui nome del pacchetto corrisponda al valore passato nella richiesta.
Messaggio troppo grande: verifica che la dimensione totale dei dati del payload inclusi in un messaggio non superi i limiti di FCM: 4096 byte per la maggior parte dei messaggi o 2048 byte nel caso di messaggi agli argomenti. Sono incluse sia le chiavi sia i valori.
Chiave dati non valida: verifica che i dati del payload non contengano una chiave (ad esempio da, gcm o qualsiasi valore con prefisso google) utilizzata internamente da FCM. Tieni presente che alcune parole (come collapse_key) vengono utilizzate anche da FCM, ma sono consentite nel payload. In questo caso, il valore del payload verrà sostituito dal valore FCM.
TTL non valido: verifica che il valore utilizzato in ttl sia un numero intero che rappresenta una durata in secondi compresa tra 0 e 2.419.200 (4 settimane).
Parametri non validi: verifica che i parametri forniti abbiano il nome e il tipo corretti.
UNREGISTERED (codice di errore HTTP = 404) L'istanza dell'app è stata annullata da FCM. In genere, questo significa che il token utilizzato non è più valido e deve essere utilizzato un nuovo token. Questo errore può essere causato da token di registrazione mancanti o non registrati.
Registrazione mancante: se il target del messaggio è un valore token, verifica che la richiesta contenga un token di registrazione.
Non registrato: un token di registrazione esistente potrebbe non essere più valido in diversi scenari, tra cui:
- Se l'app client annulla la registrazione con FCM.
- Se l'app client viene annullata automaticamente, il che può accadere se l'utente disinstalla l'applicazione. Ad esempio, su iOS, se il servizio di feedback APN ha segnalato il token APN come non valido.
- Se il token di registrazione scade (ad esempio, Google potrebbe decidere di aggiornare i token di registrazione o il token APN è scaduto per i dispositivi iOS).
- Se l'app client viene aggiornata, ma la nuova versione non è configurata per ricevere messaggi.
In tutti questi casi, rimuovi questo token di registrazione dal server dell'app e smetti di utilizzarlo per inviare messaggi.
SENDER_ID_MISMATCH (codice di errore HTTP = 403) L'ID mittente autenticato è diverso dall'ID mittente per il token di registrazione. Un token di registrazione è associato a un determinato gruppo di mittenti. Quando un'app client si registra a FCM, deve specificare quali mittenti sono autorizzati a inviare messaggi. Devi utilizzare uno di questi ID mittente quando invii messaggi all'app client. Se passi a un mittente diverso, i token di registrazione esistenti non funzioneranno.
QUOTA_EXCEEDED (codice di errore HTTP = 429) Limite di invio superato per la destinazione del messaggio. Viene restituita un'estensione di tipo google.rpc.QuotaFailure per specificare quale quota è stata superata. Questo errore può essere causato dal superamento della quota di frequenza dei messaggi, della quota di frequenza dei messaggi del dispositivo o della quota di frequenza dei messaggi dell'argomento.
Frequenza dei messaggi superata: la frequenza di invio dei messaggi è troppo elevata. Devi ridurre la frequenza complessiva di invio dei messaggi. Utilizza il backoff esponenziale con un ritardo iniziale minimo di 1 minuto per riprovare a inviare i messaggi rifiutati.
Frequenza dei messaggi del dispositivo superata: la frequenza dei messaggi inviati a un determinato dispositivo è troppo elevata. Consulta la sezione Limitazione di frequenza dei messaggi per un singolo dispositivo. Riduci il numero di messaggi inviati a questo dispositivo e utilizza il backoff esponenziale per riprovare l'invio.
Frequenza dei messaggi dell'argomento superata: la frequenza dei messaggi inviati agli iscritti a un determinato argomento è troppo elevata. Riduci il numero di messaggi inviati per questo argomento e utilizza il backoff esponenziale con un ritardo iniziale minimo di 1 minuto per riprovare l'invio.
UNAVAILABLE (codice di errore HTTP = 503) Il server è sovraccarico. Il server non è riuscito a elaborare la richiesta in tempo. Riprova la stessa richiesta, ma devi:
- Rispettare l'intestazione Retry-After se è inclusa nella risposta del server di connessione FCM.
- Implementa il backoff esponenziale nel meccanismo di ripetizione dei tentativi. (ad es. se hai atteso un secondo prima del primo nuovo tentativo, attendi almeno due secondi prima del successivo, poi quattro secondi e così via). Se invii più messaggi, valuta la possibilità di applicare il jittering. Per saperne di più, consulta Gestione dei nuovi tentativio controlla la dashboard dello stato di FCM per identificare eventuali interruzioni del servizio in corso che interessano FCM. I mittenti che causano problemi rischiano di essere inseriti in una lista bloccata.
INTERNAL (codice di errore HTTP = 500) Si è verificato un errore interno sconosciuto. Si è verificato un errore del server durante il tentativo di elaborazione della richiesta. Puoi riprovare la stessa richiesta seguendo i suggerimenti riportati in Gestione dei nuovi tentativi o controllando la dashboard dello stato di FCM. per identificare eventuali interruzioni del servizio in corso che interessano FCM. Se l'errore persiste, contatta l'assistenza Firebase.
THIRD_PARTY_AUTH_ERROR (codice di errore HTTP = 401) Il certificato APN o la chiave di autenticazione delle notifiche push web non sono validi o sono mancanti. Non è stato possibile inviare un messaggio indirizzato a un dispositivo iOS o a una registrazione di notifiche push web. Verifica la validità delle tue credenziali di sviluppo e produzione.

Codici di errore dell'SDK Admin

La tabella seguente elenca i codici di errore dell'API Firebase Admin FCM e le relative descrizioni, inclusi i passaggi di risoluzione consigliati.

Codice di errore Descrizione e passaggi per la risoluzione
messaging/invalid-argument È stato fornito un argomento non valido a un metodo FCM. Il messaggio di errore dovrebbe contenere informazioni aggiuntive.
messaging/invalid-recipient Il destinatario del messaggio non è valido. Il messaggio di errore dovrebbe contenere informazioni aggiuntive.
messaging/invalid-payload È stato fornito un oggetto payload del messaggio non valido. Il messaggio di errore dovrebbe contenere informazioni aggiuntive.
messaging/invalid-data-payload-key Il payload del messaggio di dati contiene una chiave non valida. Consulta la documentazione di riferimento per DataMessagePayload per le chiavi limitate.
messaging/payload-size-limit-exceeded Il payload del messaggio fornito supera i limiti di dimensioni di FCM. Il limite è di 4096 byte per la maggior parte dei messaggi. Per i messaggi inviati agli argomenti, il limite è di 2048 byte. Le dimensioni totali del payload includono sia le chiavi che i valori.
messaging/invalid-options È stato fornito un oggetto opzioni messaggio non valido. Il messaggio di errore dovrebbe contenere informazioni aggiuntive.
messaging/invalid-registration-token Token di registrazione fornito non valido. Assicurati che corrisponda al token di registrazione che l'app client riceve dalla registrazione con FCM. Non troncare o aggiungere altri caratteri.
messaging/registration-token-not-registered Il token di registrazione fornito non è registrato. Un token di registrazione precedentemente valido può essere annullato per diversi motivi, tra cui:
  • L'app client ha annullato la registrazione da FCM.
  • La registrazione dell'app client è stata annullata automaticamente. Questo può accadere se l'utente disinstalla l'applicazione o, sulle piattaforme Apple, se il servizio di feedback APN ha segnalato il token APN come non valido.
  • Il token di registrazione è scaduto. Ad esempio, Google potrebbe decidere di aggiornare i token di registrazione oppure il token APN potrebbe essere scaduto per i dispositivi Apple.
  • L'app client è stata aggiornata, ma la nuova versione non è configurata per ricevere messaggi.
In tutti questi casi, rimuovi questo token di registrazione e smetti di utilizzarlo per inviare messaggi.
messaging/invalid-package-name Il messaggio era indirizzato a un token di registrazione il cui nome del pacchetto non corrisponde all'opzione restrictedPackageName fornita.
messaging/message-rate-exceeded La frequenza dei messaggi inviati a un determinato target è troppo elevata. Riduci il numero di messaggi inviati a questo dispositivo o argomento e non riprovare immediatamente a inviare a questo target.
messaging/device-message-rate-exceeded La frequenza dei messaggi inviati a un determinato dispositivo è troppo elevata. Riduci il numero di messaggi inviati a questo dispositivo e non riprovare immediatamente a inviare messaggi a questo dispositivo.
messaging/topics-message-rate-exceeded La frequenza dei messaggi inviati agli abbonati a un determinato argomento è troppo alta. Riduci il numero di messaggi inviati per l'argomento e non riprovare immediatamente a inviare messaggi all'argomento.
messaging/topics-subscription-rate-exceeded La frequenza delle richieste di gestione delle sottoscrizioni a un determinato argomento è troppo elevata. Riduci il numero di richieste inviate per l'argomento e non riprovare immediatamente a inviare la richiesta.
messaging/too-many-topics Un token di registrazione è stato iscritto al numero massimo di argomenti e non può essere iscritto ad altri.
messaging/invalid-apns-credentials Non è stato possibile inviare un messaggio destinato a un dispositivo Apple perché il certificato SSL APN richiesto non è stato caricato o è scaduto. Controlla la validità dei certificati di sviluppo e produzione.
messaging/mismatched-credential La credenziale utilizzata per autenticare questo SDK non dispone dell'autorizzazione per inviare messaggi al dispositivo corrispondente al token di registrazione fornito. Assicurati che la credenziale e il token di registrazione appartengano allo stesso progetto Firebase. Consulta Aggiungi Firebase alla tua app per la documentazione su come autenticare i Firebase Admin SDK.
messaging/authentication-error L'SDK non è riuscito ad autenticarsi ai server FCM. Assicurati di autenticare Firebase Admin SDK con una credenziale che disponga delle autorizzazioni appropriate per inviare messaggi FCM. Consulta Aggiungi Firebase alla tua app per la documentazione su come autenticare i Firebase Admin SDK.
messaging/server-unavailable Il server FCM non è riuscito a elaborare la richiesta in tempo. Devi riprovare la stessa richiesta, ma devi:
  • Rispetta l'intestazione Retry-After se è inclusa nella risposta del server di connessione FCM.
  • Implementa il backoff esponenziale nel meccanismo di ripetizione dei tentativi. Ad esempio, se hai atteso un secondo prima del primo nuovo tentativo, attendi almeno due secondi prima del successivo, poi quattro secondi e continua ad aumentare l'intervallo di secondi. Se invii più messaggi, ritarda ciascuno in modo indipendente di un ulteriore intervallo di tempo casuale per evitare di inviare una nuova richiesta per tutti i messaggi contemporaneamente.
I mittenti che causano problemi rischiano di essere inseriti nella lista bloccata.
messaging/internal-error Il server FCM ha riscontrato un errore durante il tentativo di elaborare la richiesta. Puoi riprovare la stessa richiesta seguendo i requisiti elencati nella riga messaging/server-unavailable precedente. Se l'errore persiste, segnala il problema al nostro canale di assistenza Segnalazione di bug.
messaging/unknown-error È stato restituito un errore del server sconosciuto. Per ulteriori dettagli, consulta la risposta non elaborata del server nel messaggio di errore. Se ricevi questo errore, segnala il messaggio di errore completo al nostro canale di assistenza per le segnalazioni di bug.