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.
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.
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>" } }
Proprietà | Tipo di valore | Descrizione |
---|---|---|
| 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. |
| 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. |
| 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à |
| Stringa | ID traccia che puoi includere quando contatti l'Assistenza diretta. Questo ID può aiutarci con il debug dell'errore. |
| Stringa | Combinazione di codice di errore e relativo titolo. Per esempio: |
| Stringa | Prodotto di messaggistica. Corrisponderà sempre alla stringa |
| Stringa | Tipo di errore. |
{ "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" } }
Codice | Descrizione | Possibili soluzioni | Codice di stato HTTP |
---|---|---|---|
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. |
Non autorizzato |
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. |
Errore interno del server |
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. |
Non consentito |
Token d'accesso scaduto | Il token d'accesso è scaduto. |
Non autorizzato | |
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. |
Non consentito |
Codice | Descrizione | Possibili soluzioni | Codice di stato HTTP |
---|---|---|---|
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. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Richiesta non valida |
Codice | Descrizione | Possibili soluzioni | Codice di stato HTTP |
---|---|---|---|
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. |
Non consentito |
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. |
Non consentito |
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. |
Non consentito |
Codice | Descrizione | Possibili soluzioni | Codice di stato HTTP |
---|---|---|---|
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. |
Richiesta non valida |
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. |
Servizio non disponibile |
Valore parametro non valido | Il numero di telefono aziendale è stato eliminato. | Verifica che il numero di telefono aziendale sia corretto. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Errore interno del server |
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. |
Non consentito |
Parametro obbligatorio mancante | Parametro obbligatorio mancante nella richiesta. | Consulta il riferimento dell'endpoint per determinare quali parametri sono richiesti. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Errore interno del server |
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. |
Richiesta non valida |
Impossibile consegnare il messaggio | Impossibile consegnare il messaggio. Tra i motivi possono essere inclusi:
| Usando un metodo di comunicazione diverso da WhatsApp, chiedi all'utente di WhatsApp di:
|
Richiesta non valida |
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:
|
Richiesta non valida |
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. |
Errore interno del server |
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. |
Richiesta non valida |
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. |
Richiesta non valida |
Tipo messaggio non supportato | Tipo di messaggio non supportato. | Consulta Messaggi per i tipi di messaggi supportati prima di riprovare. |
Richiesta non valida |
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 Chiedi all'utente di WhatsApp di inviare il file multimediale utilizzando un metodo diverso da WhatsApp. |
Richiesta non valida |
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 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:
Puoi quindi confermare se il suo tipo MIME è supportato. Consulta Tipi di contenuti multimediali. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Non trovato |
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. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Richiesta non valida |
Flusso bloccato | Il flusso è in stato di blocco. | Correggi il flusso |
Richiesta non valida |
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 |
Richiesta non valida |
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. |
Errore interno del server |
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 |
Servizio non disponibile |
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:
|
Richiesta non valida |
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. |
Richiesta non valida |
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 |
Richiesta non valida |
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 |
Richiesta non valida |
Numero di telefono non registrato | Numero di telefono non registrato sulla piattaforma WhatsApp Business. | Registra il numero di telefono prima di riprovare. |
Richiesta non valida |
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. |
Richiesta non valida |
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. |
Richiesta non valida |