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 lo stato dell'errore. Possono anche contenere un array details con ulteriori dettagli sull'errore.

Di seguito sono riportate due risposte di errore di esempio:

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 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 il tipo type.googleapis.com/google.firebase.fcm.v1.FcmError ha un errore specifico di FCM. Per molti errori, l'array dei dettagli 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 sono validi. Viene restituita un'estensione di tipo google.rpc.BadRequest per specificare quale campo non è valido. Le possibili cause includono registrazione non valida, nome del pacchetto non valido, messaggio troppo grande, chiave di 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 a FCM. Non troncare il token né aggiungere caratteri aggiuntivi.
Nome del pacchetto non valido: assicurati che il messaggio sia indirizzato a un token di registrazione il cui nome del pacchetto corrisponda al valore passato nella richiesta.
Messaggio troppo grande: verifica che le dimensioni totali dei dati del payload inclusi in un messaggio non superino i limiti di FCM: 4096 byte per la maggior parte dei messaggi o 2048 byte nel caso di messaggi agli argomenti. Sono inclusi sia le chiavi sia i valori.
Chiave di dati non valida: verifica che i dati del payload non contengano una chiave (ad esempio from, gcm o qualsiasi valore con prefisso google) utilizzata internamente da FCM. Tieni presente che alcune parole (ad esempio collapse_key) vengono utilizzate anche da FCM, ma sono consentite nel payload, nel qual 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 la registrazione da FCM. Di solito, 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 da token non registrati.
Registrazione mancante: se la destinazione 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 a FCM.
- Se la registrazione dell'app client viene annullata automaticamente, cosa che può accadere se l'utente disinstalla l'applicazione. Ad esempio, su iOS, se il servizio di feedback APNs ha segnalato il token APNs come non valido.
- Se il token di registrazione scade (ad esempio, Google potrebbe decidere di aggiornare i token di registrazione o il token APNs è 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 del 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. Quando invii messaggi all'app client, devi utilizzare uno di questi ID mittente. Se passi a un altro mittente, i token di registrazione esistenti non funzioneranno.
QUOTA_EXCEEDED (codice di errore HTTP = 429) Il limite di invio è stato 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 a un determinato dispositivo è troppo elevata. Consulta il limite di frequenza dei messaggi per un singolo dispositivo. Riduci il numero di messaggi inviati a questo dispositivo e utilizza il backoff esponenziale per riprovare a inviare.
Frequenza dei messaggi dell'argomento superata: la frequenza dei messaggi agli abbonati 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 a inviare.
UNAVAILABLE (codice di errore HTTP = 503) Il server è sovraccarico. Il server non è riuscito a elaborare la richiesta in tempo. Riprova a inviare la stessa richiesta, ma devi:
- Rispettare l'intestazione Retry-After se è inclusa nella risposta del server di connessione FCM.
- Implementare il backoff esponenziale nel meccanismo di nuovi tentativi. (ad es. se hai atteso un secondo prima del primo nuovo tentativo, attendi almeno due secondi prima del successivo, poi 4 secondi e così via). Se invii più messaggi, valuta la possibilità di applicare il jittering. Per ulteriori informazioni, consulta Gestire i nuovi tentativi, o controlla la dashboard dello stato di FCM per verificare se sono in corso interruzioni del servizio che interessano FCM. I mittenti che causano problemi rischiano di essere inseriti in una lista di blocco.
INTERNAL (codice di errore HTTP = 500) Si è verificato un errore interno sconosciuto. Il server ha riscontrato un errore durante il tentativo di elaborazione della richiesta. Puoi riprovare a inviare la stessa richiesta seguendo i suggerimenti riportati in Gestire i nuovi tentativi o controllando la dashboard dello stato di FCM. per verificare se sono in corso interruzioni del servizio che interessano FCM. Se l' errore persiste, contatta l'assistenza Firebase.
THIRD_PARTY_AUTH_ERROR (codice di errore HTTP = 401) Il certificato APNs o la chiave di autenticazione push web non è valido o è mancante. Non è stato possibile inviare un messaggio destinato a un dispositivo iOS o a una registrazione push web. Controlla la validità delle credenziali di sviluppo e produzione.

Codici di errore dell'SDK Admin

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

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 previsto 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. Per le chiavi con limitazioni, consulta la documentazione di riferimento per DataMessagePayload.
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 sia i valori.
messaging/invalid-options È stato fornito un oggetto di opzioni del messaggio non valido. Il messaggio di errore dovrebbe contenere informazioni aggiuntive.
messaging/invalid-registration-token È stato fornito un token di registrazione non valido. Assicurati che corrisponda al token di registrazione che l'app client riceve dalla registrazione a FCM. Non troncare il token né aggiungere caratteri aggiuntivi.
messaging/registration-token-not-registered Il token di registrazione fornito non è registrato. Un token di registrazione precedentemente valido può essere annullato per una serie di motivi, tra cui:
  • L'app client ha annullato la registrazione a 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 APNs ha segnalato il token APNs come non valido.
  • Il token di registrazione è scaduto. Ad esempio, Google potrebbe decidere di aggiornare i token di registrazione o il token APNs 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 è stato 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 a una determinata destinazione è troppo elevata. Riduci il numero di messaggi inviati a questo dispositivo o argomento e non riprovare immediatamente a inviare a questa destinazione.
messaging/device-message-rate-exceeded La frequenza dei messaggi a un determinato dispositivo è troppo elevata. Riduci il numero di messaggi inviati a questo dispositivo e non riprovare immediatamente a inviare a questo dispositivo.
messaging/topics-message-rate-exceeded La frequenza dei messaggi agli abbonati a un determinato argomento è troppo elevata. Riduci il numero di messaggi inviati per questo argomento e non riprovare immediatamente a inviare a questo argomento.
messaging/too-many-topics Un token di registrazione è stato abbonato al numero massimo di argomenti e non può essere abbonato ad altri.
messaging/invalid-apns-credentials Non è stato possibile inviare un messaggio destinato a un dispositivo Apple perché il certificato SSL APNs 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. Per la documentazione su come autenticare gli Firebase Admin SDKs, consulta Aggiungere Firebase alla tua app.
messaging/authentication-error L'SDK non è riuscito ad autenticarsi ai FCM server. Assicurati di autenticare il Firebase Admin SDK con una credenziale che disponga delle autorizzazioni appropriate per inviare FCM messaggi. Per la documentazione su come autenticare gli Firebase Admin SDKs, consulta Aggiungere Firebase alla tua app.
messaging/server-unavailable Il server FCM non è riuscito a elaborare la richiesta in tempo. Devi riprovare a inviare la stessa richiesta, ma devi:
  • Rispettare l'intestazione Retry-After se è inclusa nella risposta del server di connessione FCM.
  • Implementare il backoff esponenziale nel meccanismo di nuovi 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 ognuno in modo indipendente di un importo casuale aggiuntivo per evitare di inviare una nuova richiesta per tutti i messaggi contemporaneamente.
I mittenti che causano problemi rischiano di essere inseriti in una lista di blocco.
messaging/internal-error Il server FCM ha riscontrato un errore durante il tentativo di elaborare la richiesta. Puoi riprovare a inviare la stessa richiesta seguendo i requisiti elencati nella riga precedente messaging/server-unavailable. Se l' errore persiste, segnala il problema al nostro canale di assistenza per la segnalazione di bug.
messaging/unknown-error È stato restituito un errore server sconosciuto. Per ulteriori dettagli, consulta la risposta del server non elaborata nel messaggio di errore. Se ricevi questo errore, segnala il messaggio di errore completo al nostro canale di assistenza per la segnalazione di bug.