Codici di errore dell'API Cloud

L'API Cloud è sviluppata sull'API Graph, quindi se non hai familiarità con la gestione delle risposte di errore dell'API Graph consulta la documentazione sulla gestione degli errori dell'API Graph.

In generale, ti consigliamo di creare una logica di gestione degli errori specifica per la tua app in base ai valori code e alle proprietà del payload details. Queste proprietà e i loro valori sono maggiormente indicativi dell'errore sottostante.

I titoli del codice, che non hanno una proprietà dedicata nei payload di risposta degli errori dell'API, sono inclusi come parte del valore message. Ti consigliamo, tuttavia, di non affidarti ai titoli per la logica di gestione degli errori, poiché essi col tempo diventeranno obsoleti.

Ricezione di errori: sincroni e asincroni

Gli errori dell'API Cloud vengono restituiti in modo sincrono come risposta dell'API Graph, asincrono via webhook o talvolta attraverso entrambi i metodi.

Quando si lavora con l'API Cloud è una buona pratica monitorare sia la risposta dell'API Graph sia il webhook messaggi per la gestione degli errori. Se hai effettuato l'iscrizione al campo webhook messages, riceverai una notifica degli errori non appena si verificano per i tipi di errori asincroni supportati.

Webhook e sintassi delle risposte di errore

Gli errori dell'API Cloud possono essere mostrati nei seguenti oggetti webhook:

API Cloud

  • entry.changes.value.errors
  • entry.changes.value.messages.errors

API On-Premises

  • errors

Sintassi della risposta di errore

{
  "error": {
    "message": "<MESSAGE>",
    "type": "<TYPE>",
    "code": <CODE>,
    "error_data": {
        "messaging_product": "whatsapp",
        "details": "<DETAILS>"
    },
    "error_subcode": <ERROR_SUBCODE>
    "fbtrace_id": "<FBTRACE_ID>"
  }
}

Contenuti delle risposte di errore

Proprietà Tipo di valore Descrizione

code

Numero intero

Codice di errore. Ti consigliamo di creare una logica di gestione degli errori specifica per la tua app sulla base dei codici di errore piuttosto che dei sottocodici o dei codici di stato della risposta HTTP.

details

Stringa

Descrizione dell'errore e della relativa causa più probabile. Può anche contenere informazioni su come affrontare l'errore, ad esempio quale parametro non è valido o quali valori sono accettabili.

error_subcode

Numero intero

Obsoleto. Non sarà restituito nelle risposte a partire dalla versione 16.0.


Sottocodice dell'API Graph. Non tutte le risposte includeranno un sottocodice, per questo ti consigliamo piuttosto di creare una tua logica di gestione degli errori sulla base delle proprietà code e details.

fbtrace_id

Stringa

ID traccia che puoi includere quando contatti l'Assistenza diretta. Questo ID può aiutarci con il debug dell'errore.

message

Stringa

Combinazione di codice di errore e relativo titolo. Per esempio: (#130429) Rate limit hit.

messaging_product

Stringa

Prodotto di messaggistica. Corrisponderà sempre alla stringa whatsapp per le risposte dell'API Cloud.

type

Stringa

Tipo di errore.

Esempio di risposta

{
  "error": {
    "message": "(#130429) Rate limit hit",
    "type": "OAuthException",
    "code": 130429,
    "error_data": {
        "messaging_product": "whatsapp", 
        "details": "Message failed to send because there were too many messages sent from this phone number in a short period of time"
    },
    "error_subcode": 2494055,
    "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

Codici di errore

Errori di autorizzazione

Codice Descrizione Possibili soluzioni Codice di stato HTTP

0

AuthException

Non siamo stati in grado di autenticare l'utente dell'app.

In genere questo significa che il token d'accesso incluso è scaduto, è stato invalidato o che l'utente dell'app ha modificato un'impostazione per impedire a tutte le app di accedere ai propri dati. Ti consigliamo di ottenere un nuovo token d'accesso.

401

Non autorizzato

3

Metodo API

Problema di funzionalità o autorizzazioni.

Usa il debugger dei token d'accesso per verificare che la tua app disponga delle autorizzazioni richieste dall'endpoint. Consulta Risoluzione dei problemi.

500

Errore interno del server

10

Autorizzazione negata

L'autorizzazione non è stata concessa o è stata rimossa.

Usa il debugger dei token d'accesso per verificare che la tua app disponga delle autorizzazioni richieste dall'endpoint. Consulta Risoluzione dei problemi.

Assicurati che il numero di telefono usato per impostare la chiave pubblica dell'azienda sia consentito.

403

Non consentito

190

Token d'accesso scaduto

Il token d'accesso è scaduto.

Ottieni un nuovo token d'accesso.

401

Non autorizzato

200-299

Autorizzazione API

L'autorizzazione non è stata concessa o è stata rimossa.

Usa il debugger dei token d'accesso per verificare che la tua app disponga delle autorizzazioni richieste dall'endpoint. Consulta Risoluzione dei problemi.

403

Non consentito

Errori di throttling

Codice Descrizione Possibili soluzioni Codice di stato HTTP

4

Troppe chiamate API

L'app ha raggiunto il rate limiting di chiamate API.

Carica l'app nella Dashboard gestione app e visualizza la sezione Rate limiting dell'app per controllare se l'app ha raggiunto il rate limiting. Se è così, riprova più tardi o riduci la frequenza o la quantità di query all'API eseguite dall'app.

400

Richiesta non valida

80007

Problemi con il rate limiting

L'account WhatsApp Business ha raggiunto il rate limiting.

Consulta Rate limiting dell'account WhatsApp Business. Riprova più tardi o riduci la frequenza o la quantità di query all'API eseguite dall'app.

400

Richiesta non valida

130429

Rate limiting raggiunto

Il throughput messaggi dell'API Cloud è stato raggiunto.

L'app ha raggiunto il limite di throughput dell'API. Consulta Throughput. Riprova più tardi o riduci la frequenza con cui l'app invia messaggi.

400

Richiesta non valida

131048

Rate limiting spam raggiunto

Impossibile inviare il messaggio perché esistono limitazioni al numero di messaggi che possono essere inviati da questo numero di telefono. Questo errore può essere dovuto a un numero eccessivo di messaggi precedenti bloccati o contrassegnati come spam.

Controlla lo stato di qualità in WhatsApp Manager e consulta la documentazione sul rate limiting basato sulla qualità per maggiori informazioni.

400

Richiesta non valida

131056

Rate limiting della coppia (account business, account consumatore) raggiunto

Troppi messaggi inviati dal numero di telefono del mittente al numero di telefono dello stesso destinatario in un breve periodo di tempo.

Se vuoi inviare messaggi allo stesso numero di telefono, aspetta e ripeti l'operazione. Per inviare messaggi a un numero di telefono diverso non è necessario attendere.

400

Richiesta non valida

133016

Rate limiting di cancellazione della registrazione account superato

Registrazione o cancellazione della registrazione non andata a buon fine perché ci sono stati troppi tentativi per questo numero di telefono in poco tempo

Il numero di telefono aziendale è stato bloccato perché ha raggiunto il limite di tentativi di registrazione/cancellazione della registrazione. Riprova quando il numero sarà sbloccato. Consulta "Limitazioni" nel documento Registrazione.

400

Richiesta non valida

Errori di integrità

Codice Descrizione Possibili soluzioni Codice di stato HTTP

368

Bloccato temporaneamente per violazioni delle normative

All'account WhatsApp Business associato all'app sono state applicate restrizioni o l'account è stato disabilitato per violazione di una normativa della piattaforma.

Consulta il documento Applicazione della normativa per ulteriori informazioni sulle violazioni delle normative e sulla relativa modalità di risoluzione.

403

Non consentito

130497

L'account business non può inviare messaggi agli utenti in questo Paese.

L'account WhatsApp Business non può inviare messaggi agli utenti in determinati Paesi.

Consulta la Normativa sui messaggi di WhatsApp Business per dettagli sui Paesi autorizzati per l'invio di messaggi nella tua categoria aziendale.

403

Non consentito

131031

Account bloccato

All'account WhatsApp Business associato all'app sono state applicate restrizioni o l'account è stato disabilitato per aver violato una normativa della piattaforma oppure non siamo stati in grado di verificare i dati inclusi nella richiesta con i dati presenti nell'account WhatsApp Business (ad esempio, il PIN in due passaggi incluso nella richiesta non è corretto).

Consulta il documento Applicazione della normativa per ulteriori informazioni sulle violazioni delle normative e sulla relativa modalità di risoluzione.


Puoi anche utilizzare l'API Health Status, che fornisce ulteriori informazioni in merito al motivo o ai motivi per il blocco dell'account.

403

Non consentito

Altri errori

Codice Descrizione Possibili soluzioni Codice di stato HTTP

1

API sconosciuta

Richiesta non valida o possibile errore del server.

Consulta la pagina Stato della piattaforma WhatsApp Business per vedere le informazioni sullo stato dell'API. Se non ci sono interruzioni del server, consulta il riferimento all'endpoint e verifica che la tua richiesta sia formattata correttamente e che soddisfi tutti i requisiti dell'endpoint.

400

Richiesta non valida

2

Servizio API

Dovuto temporaneamente a un tempo di inattività o a uno stato di sovraccarico.

Consulta la pagina Stato della piattaforma WhatsApp Business per vedere le informazioni sullo stato dell'API prima di riprovare.

503

Servizio non disponibile

33

Valore parametro non valido

Il numero di telefono aziendale è stato eliminato.

Verifica che il numero di telefono aziendale sia corretto.

400

Richiesta non valida

100

Parametro non valido

La richiesta includeva uno o più parametri non supportati o con errori di ortografia.

Consulta il riferimento dell'endpoint per determinare quali parametri sono supportati e come sono scritti.

Quando imposti la chiave pubblica aziendale, assicurati che sia una chiave pubblica RSA valida a 2048 bit in formato PEM.

Assicurati che non ci siano discrepanze tra l'ID del numero di telefono che stai registrando e un ID del numero di telefono memorizzato precedentemente.

Assicurati che il tuo parametro rispetti le eventuali limitazioni di lunghezza per il tipo.

400

Richiesta non valida

130472

Il numero dell'utente fa parte di un esperimento

Il messaggio non è stato inviato come parte di un esperimento.

Consulta Esperimento sui messaggi di marketing.

400

Richiesta non valida

131000

Si è verificato un errore

Impossibile inviare il messaggio a causa di un errore sconosciuto.

Al momento dell'impostazione di una chiave pubblica aziendale, non è stato possibile calcolare la firma, chiamare l'endpoint GraphQL oppure l'endpoint GraphQL ha restituito un errore.

Riprova. Se l'errore persiste, apri un ticket dell'Assistenza diretta.

500

Errore interno del server

131005

Accesso negato

L'autorizzazione non è stata concessa o è stata rimossa.

Usa il debugger dei token d'accesso per verificare che la tua app disponga delle autorizzazioni richieste dall'endpoint. Consulta Risoluzione dei problemi.

403

Non consentito

131008

Parametro obbligatorio mancante

Parametro obbligatorio mancante nella richiesta.

Consulta il riferimento dell'endpoint per determinare quali parametri sono richiesti.

400

Richiesta non valida

131009

Valore parametro non valido

Uno o più valori dei parametri non sono validi.

Consulta il riferimento dell'endpoint per determinare quali valori sono supportati per ciascun parametro e il documento Numeri di telefono per indicazioni sulla modalità di aggiunta di un numero di telefono a un account WhatsApp Business.

400

Richiesta non valida

131016

Servizio non disponibile

Un servizio è temporaneamente non disponibile.

Consulta la pagina Stato della piattaforma WhatsApp Business per vedere le informazioni sullo stato dell'API prima di riprovare.

500

Errore interno del server

131021

Destinatario e mittente non possono coincidere

Il numero di telefono di mittente e destinatario coincidono.

Invia un messaggio a un numero di telefono diverso da quello del mittente.

400

Richiesta non valida

131026

Impossibile consegnare il messaggio

Impossibile consegnare il messaggio. Tra i motivi possono essere inclusi:

  • Il numero di telefono del destinatario non è un numero di telefono WhatsApp.
  • Invio di un modello di autenticazione a un utente di WhatsApp con prefisso di chiamata internazionale +91 (India). Attualmente non è possibile inviare modelli di autenticazione agli utenti di WhatsApp in India.
  • Il destinatario non ha accettato le nostre nuove Condizioni d'uso e l'Informativa sulla privacy.
  • Il destinatario che utilizza una versione di WhatsApp precedente, deve usare la seguente versione WhatsApp o superiore:
    • Android: 2.21.15.15
    • SMBA: 2.21.15.15
    • iOS: 2.21.170.4
    • SMBI: 2.21.170.4
    • KaiOS: 2.2130.10
    • Web: 2.2132.6

Usando un metodo di comunicazione diverso da WhatsApp, chiedi all'utente di WhatsApp di:

  • confermare di essere effettivamente in grado di inviare un messaggio al tuo numero di telefono WhatsApp Business;
  • confermare di aver accettato le nostre Condizioni d'uso più recenti (Impostazioni > Aiuto o Impostazioni > Informazioni sull'applicazione richiederà l'accettazione delle condizioni/delle normative più recenti se non ancora fatto);
  • effettuare l'aggiornamento alla versione più recente del client di WhatsApp.

400

Richiesta non valida

131042

Idoneità aziendale - Problema di pagamento

Si è verificato un errore correlato al metodo di pagamento.

Consulta Informazioni sulla fatturazione per gli account WhatsApp Business e verifica di aver configurato correttamente la fatturazione.

Problemi comuni:

  • L'account di pagamento non è collegato a un account WhatsApp Business
  • La linea di credito è oltre il limite
  • Linea di credito (account di pagamento) non impostata o attiva
  • Account WhatsApp Business eliminato
  • Account WhatsApp Business sospeso
  • Fuso orario non impostato
  • Valuta non impostata
  • La richiesta di MessagingFor (On Behalf Of) è in attesa o rifiutata
  • Soglia delle conversazioni gratuite superata senza un metodo di pagamento valido

400

Richiesta non valida

131045

Certificato errato

Impossibile inviare il messaggio a causa di un errore di registrazione del numero di telefono.

Registra il numero di telefono prima di riprovare.

500

Errore interno del server

131047

Messaggio di coinvolgimento

Sono trascorse più di 24 ore dall'ultima risposta del destinatario al numero del mittente.

Invia al destinatario un messaggio avviato dall'azienda utilizzando un modello di messaggio.

400

Richiesta non valida

131049

Meta ha scelto di non consegnare.

Questo messaggio non è stato consegnato per mantenere l'integrità delle interazioni nell'ecosistema.

Non riprovare immediatamente se ricevi questo codice di errore e sospetti che sia dovuto al limite. Invece, prova ad aumentare gradualmente gli incrementi di tempo fino alla consegna del messaggio poiché il limite potrebbe applicarsi a diversi intervalli temporali.

Per informazioni aggiuntive, consulta Limiti dei modelli di messaggi di marketing per utente.

400

Richiesta non valida

131051

Tipo messaggio non supportato

Tipo di messaggio non supportato.

Consulta Messaggi per i tipi di messaggi supportati prima di riprovare.

400

Richiesta non valida

131052

Errore di download contenuto multimediale

Impossibile scaricare il contenuto multimediale inviato dall'utente.

Non è stato possibile scaricare i contenuti multimediali inclusi nel messaggio dell'utente WhatsApp. Per maggiori informazioni, consulta il valore error.error_data.details in qualsiasi webhook messages attivato quando è stato ricevuto questo messaggio.

Chiedi all'utente di WhatsApp di inviare il file multimediale utilizzando un metodo diverso da WhatsApp.

400

Richiesta non valida

131053

Errore di caricamento contenuto multimediale

Impossibile caricare il contenuto multimediale usato nel messaggio.

Non siamo riusciti a caricare il contenuto multimediale per uno o più motivi, ad esempio perché il tipo di contenuto multimediale non è supportato.

Per maggiori informazioni, consulta il valore error.error_data.details in qualsiasi webhook messages attivato quando l'invio del messaggio non è andato a buon fine.

Consigliamo di controllare i file multimediali che hanno restituito errori e verificare che siano effettivamente supportati. Ad esempio, in UNIX puoi controllare i file attraverso la linea di comando per determinarne il tipo MIME:

file -I rejected-file.mov

Puoi quindi confermare se il suo tipo MIME è supportato. Consulta Tipi di contenuti multimediali.

400

Richiesta non valida

131057

Account in modalità manutenzione

Account business in modalità manutenzione

L'account WhatsApp Business è in modalità manutenzione. Il motivo potrebbe essere che l'account è in fase di aggiornamento del throughput.

500

Richiesta non valida

132000

Conteggio parametri modello non corrispondente

Il numero di valori dei parametri variabili inclusi nella richiesta non corrispondeva al numero di parametri variabili definiti nel modello.

Consulta le Linee guida per i modelli di messaggi e assicurati che la richiesta includa tutti i valori dei parametri variabili che sono stati definiti nel modello.

400

Richiesta non valida

132001

Modello inesistente

Il modello non esiste nella lingua specificata oppure non è stato approvato.

Assicurati che il modello sia stato approvato e che il nome e la lingua del modello siano corretti. Assicurati di seguire le linee guida per i modelli di messaggi.

404

Non trovato

132005

Testo attivato modello troppo lungo

Il testo tradotto è troppo lungo.

Controlla WhatsApp Manager per verificare che il modello sia stato tradotto. Consulta Valutazione di qualità e stato del modello.

400

Richiesta non valida

132007

Criteri caratteri formato modello non rispettati

Il contenuto del modello viola una normativa di WhatsApp.

Consulta Motivi del rifiuto per determinare le possibili cause della violazione.

400

Richiesta non valida

132012

Formato parametro modello non corrispondente

Valori dei parametri variabili formattati in modo errato.

I valori dei parametri variabili inclusi nella richiesta non usano il formato specificato nel modello. Consulta Linee guida per i modelli di messaggi.

400

Richiesta non valida

132015

Modello in pausa

Il modello è in pausa a causa della bassa qualità e non può essere inviato in un modello di messaggio.

Modifica il modello per migliorarne la qualità e riprovare dopo l'approvazione.

400

Richiesta non valida

132016

Modello disabilitato

Il modello è stato messo in pausa troppe volte a causa della bassa qualità e ora è stato disabilitato definitivamente.

Crea un nuovo modello con contenuti diversi.

400

Richiesta non valida

132068

Flusso bloccato

Il flusso è in stato di blocco.

Correggi il flusso

400

Richiesta non valida

132069

Flusso in throttling

Il flusso è in stato di throttling e 10 messaggi che usano questo flusso sono già stati inviati nell'ultima ora.

Correggere il flusso

400

Richiesta non valida

133000

Annullamento registrazione incompleto

Un precedente tentativo di annullamento della registrazione non è andato a buon fine.

Annulla la registrazione del numero prima di registrarlo di nuovo.

500

Errore interno del server

133004

Server temporaneamente non disponibile

Il server è temporaneamente non disponibile.

Per informazioni sullo stato dell'API, consulta la pagina Stato della piattaforma WhatsApp Business e controlla il valore details della risposta prima di riprovare.

503

Servizio non disponibile

133005

PIN verifica in due passaggi non corrispondente

PIN della verifica in due passaggi errato.

Verifica che il PIN della verifica in due passaggi incluso nella richiesta sia corretto.


Per reimpostare il PIN della verifica in due passaggi, procedi in questo modo:


  1. Disabilita l'autorizzazione alla verifica in due passaggi.
  2. Invia una richiesta POST che includa il nuovo PIN all'endpoint Numero di telefono.

400

Richiesta non valida

133006

Richiesta nuova verifica numero di telefono

Il numero di telefono deve essere nuovamente verificato prima di procedere alla registrazione.

Verifica il numero di telefono prima di procedere alla registrazione.

400

Richiesta non valida

133008

Troppi tentativi sbagliati del PIN di verifica in due passaggi

Troppi tentativi sbagliati di inserimento del PIN per la verifica in due passaggi per questo numero di telefono.

Attendi il tempo specificato nel valore della risposta details e riprova.

400

Richiesta non valida

133009

Tentativi PIN di verifica in due passaggi troppo veloci

Il PIN della verifica in due passaggi è stato inserito troppo velocemente.

Controlla il valore della risposta details prima di riprovare.

400

Richiesta non valida

133010

Numero di telefono non registrato

Numero di telefono non registrato sulla piattaforma WhatsApp Business.

Registra il numero di telefono prima di riprovare.

400

Richiesta non valida

133015

Attendi qualche minuto prima di tentare di registrare questo numero di telefono

Il numero di telefono che stai tentando di registrare è stato eliminato di recente e l'eliminazione non è ancora completata.

Aspetta 5 minuti prima di riprovare la richiesta.

400

Richiesta non valida

135000

Errore utente generico

Impossibile inviare il messaggio a causa di un errore sconosciuto con i parametri della richiesta.

Consulta il riferimento dell'endpoint per verificare che la sintassi usata per interrogare l'endpoint sia corretta. Se continui a ricevere questo codice di errore in risposta, contatta l'assistenza clienti.

400

Richiesta non valida