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. 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 il tipo type.googleapis.com/google.firebase.fcm.v1.FcmError presenta 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 erano validi. Viene restituita un'estensione di tipo `google.rpc.BadRequest` per specificare quale campo non è valido.	Le potenziali cause 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 trasmetti al server. Assicurati che corrisponda al token di registrazione che l'app client riceve dalla registrazione a FCM. Non troncare il token o 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 inviati agli argomenti. Sono incluse sia le chiavi che i valori. Chiave dati non valida: verifica che i dati del payload non contengano una chiave (ad esempio da, gcm o qualsiasi valore con il 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. In genere, 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 la registrazione dell'app client viene annullata in 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 APNs ha segnalato che il token APNs 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 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. Tasso di messaggi superato: 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. Tasso di messaggi al dispositivo superato: il tasso di messaggi a un determinato dispositivo è troppo elevato. Consulta Limite di velocità dei messaggi a un singolo dispositivo . Riduci il numero di messaggi inviati a questo dispositivo e utilizza il backoff esponenziale per riprovare a inviarli. Tasso di messaggi dell'argomento superato: il tasso di messaggi inviati agli abbonati a un determinato argomento è troppo elevato. 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 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 nuovi tentativi. Ad esempio, se hai atteso un secondo prima del primo 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 Gestione dei tentativi o 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 nella 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 Gestione dei tentativi o controllando il dashboard di 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 era valido o mancava.	Non è stato possibile inviare un messaggio destinato a un dispositivo iOS o una registrazione push web. Controlla la validità delle credenziali di sviluppo e produzione.

Codici di errore dell'SDK Admin

La seguente tabella 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 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 dimensione di FCM. Il limite è di 4096 byte per la maggior parte dei messaggi. Per i messaggi inviati agli argomenti, il limite è di 2048 byte. La dimensione totale del payload include sia le chiavi che i valori.
`messaging/invalid-options`	È stato fornito un oggetto di opzioni per messaggi 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 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 propria registrazione da FCM. La registrazione dell'app client è stata annullata automaticamente. Ciò può accadere se l'utente disinstalla l'applicazione o, sulle piattaforme Apple, se il servizio APNs Feedback 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 inviato a un token di registrazione il cui nome del pacchetto non corrisponde all'opzione `restrictedPackageName` fornita.
`messaging/message-rate-exceeded`	Il tasso di messaggi inviati a un determinato target è troppo alto. Ridurre 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. Ridurre il numero di messaggi inviati a questo dispositivo e non riprovare immediatamente a inviarli a questo dispositivo.
`messaging/topics-message-rate-exceeded`	La frequenza dei messaggi inviati agli abbonati a un determinato argomento è troppo elevata. Riduci il numero di messaggi inviati per quell'argomento e non riprovare immediatamente a inviarli.
`messaging/too-many-topics`	Un token di registrazione è stato sottoscritto al numero massimo di argomenti e non può essere sottoscritto ad altri.
`messaging/invalid-apns-credentials`	Un messaggio destinato a un dispositivo Apple non è stato inviato 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 le credenziali e il token di registrazione appartengano allo stesso progetto Firebase. Consulta Aggiungere Firebase alla tua app per la documentazione su come autenticare i Firebase Admin SDK.
`messaging/authentication-error`	L'SDK non è riuscito ad autenticarsi sui server FCM. Assicurati di autenticare Firebase Admin SDK con una credenziale che disponga delle autorizzazioni appropriate per inviare messaggi FCM. Consulta Aggiungere 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 a inviare 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 nuovi tentativi. Ad esempio, se hai atteso un secondo prima del primo 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 ulteriore importo casuale per evitare di emettere una nuova richiesta per tutti i messaggi contemporaneamente. I mittenti che causano problemi rischiano di essere inseriti nella blocklist.
`messaging/internal-error`	Il server FCM ha riscontrato un errore durante il tentativo di elaborazione della richiesta. Puoi riprovare a inviare 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 sconosciuto del server. 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 Segnalazione di bug.