Codici di errore WhatsApp Cloud API
Qui trovi tutti i codici di errore WhatsApp Cloud API che documentiamo, in una tabella con il significato di ciascuno e l'utilità di un nuovo tentativo. La maggior parte non serve: gli errori sono deterministici, quindi la stessa richiesta fallisce nello stesso modo e un ciclo di nuovi tentativi trasforma una richiesta errata in un limite di frequenza.
Request
| Code | What it means | Retry |
|---|---|---|
| 100 | A parameter is unsupported, misspelled or malformed. | No |
| 131008 | A required parameter was not included at all. | No |
| 131009 | A parameter is present with a value the endpoint rejects. | No |
| 131021 | Sender and recipient are the same number. | No |
| 131051 | The message type is not supported, often a Coexistence limit. | No |
| 131052 | Meta could not download media a customer sent. | No |
| 131053 | Meta could not upload media you sent. Size, format or reach. | No |
Template
| Code | What it means | Retry |
|---|---|---|
| 132000 | The number of parameters does not match the template. | No |
| 132001 | No template exists with that name and language pair. | No |
| 132007 | The template breaks messaging policy. Rewrite and resubmit. | No |
| 132012 | Parameter format does not match what the template defines. | No |
| 132015 | The template is paused after a quality decline. Temporary. | Wait |
| 132016 | The template is permanently disabled. It will not come back. | No |
Window and recipient
Registration and PIN
| Code | What it means | Retry |
|---|---|---|
| 131045 | The number was never registered for Cloud API messaging. | No |
| 133010 | The number is not registered. Registration must be completed. | No |
| 133006 | The number must be verified before it can be registered. | No |
| 133005 | The two-step verification PIN was wrong. Stop guessing. | No |
| 133008 | Too many PIN attempts. Registration is locked for a period. | Wait |
Access and account
| Code | What it means | Retry |
|---|---|---|
| 190 | The access token expired or was invalidated. | No |
| 368 | The account is restricted after a policy violation. | No |
| 131031 | The account is restricted, or its data does not match Meta's. | No |
| 131042 | A payment problem on the business account blocks sending. | No |
| 131049 | Meta blocked the message to protect ecosystem health. | No |
Rate limits
Transient
Coexistence sync
Come leggere la colonna dei nuovi tentativi
Contiene tre valori e scegliere quello sbagliato è l'errore più costoso di tutta questa guida.
No significa che il fallimento è deterministico. È la richiesta, il template o lo stato del destinatario ad aver causato il problema: inviare di nuovo la stessa richiesta produce lo stesso errore e consuma capacità che ti servirà in seguito. Yes significa che il problema era dalla parte di Meta e un backoff lo risolve davvero. Wait significa che la condizione è reale ma temporanea: un limite o un blocco che si rimuove da solo. Ritentare prima che scompaia non serve e può prolungarlo.
Perché la maggior parte di questi codici non consente nuovi tentativi
Perché la piattaforma restituisce codici specifici invece di codici generici. Un parametro non valido, un template inesistente, una finestra di messaggistica chiusa e un destinatario che ha revocato il consenso sono tutti problemi riconoscibili al momento della risposta, quindi Meta li identifica invece di restituire un errore vago.
- Un problema nella richiesta non diventa corretto al secondo tentativo.
- Un problema del template è nel template, che la richiesta non può modificare.
- Un problema della finestra o del consenso riguarda lo stato del destinatario, non il tuo.
- Una limitazione dell'account è una decisione e ritentare non è un ricorso.
Cosa registrare quando arriva uno di questi codici
Quanto basta per diagnosticarlo senza riprodurlo: è la differenza tra una correzione di cinque minuti e una giornata passata a tirare a indovinare.
- La risposta completa dell'errore, incluso il trace id, richiesto dall'assistenza Meta.
- Il corpo della richiesta così come è stato inviato, non come lo avevi previsto. Di solito il problema è proprio la differenza tra i due.
- L'ID del numero di telefono, per distinguere un problema su un numero da uno che riguarda l'intero account.
- Il timestamp, per verificare il fallimento rispetto allo stato della connessione in quel momento.
I codici che esistono solo su Coexistence
Sono due e confondono perché sembrano normali errori di invio. 2593107 e 2593108 riguardano entrambi la sincronizzazione della cronologia chat, il passaggio che copia le conversazioni recenti dall'app WhatsApp Business quando un numero viene collegato per la prima volta.
Non sono errori di messaggistica e non indicano che la connessione sia fallita. Una sincronizzazione che supera il limite o avviene fuori dalla finestra prevista lascia il numero connesso e operativo, ma con meno cronologia copiata del previsto. Interpretarli come una connessione interrotta porta a scollegare il numero e ricominciare, perdendo altra cronologia invece di recuperarla.
Domande frequenti
Quali errori devo ritentare?
131016 e 131000, con backoff esponenziale. 130429, 132015 e 133008 si risolvono da soli aspettando. Tutto il resto è deterministico.
Un codice di errore significa che il mio numero è disconnesso?
Di solito no. La maggior parte riguarda la richiesta, il template o il destinatario. I problemi di connessione compaiono come webhook dell'account e della qualità, non come errori di invio.
Che cos'è un trace id?
È un identificativo nella risposta dell'errore che permette all'assistenza Meta di trovare la richiesta specifica. Registralo a ogni fallimento: senza di esso una segnalazione non può essere gestita.
Questi codici sono uguali per ogni provider?
Sì. Provengono dalla Cloud API di Meta, quindi sono identici qualunque provider abbia collegato il numero. Un provider può cambiare solo la chiarezza con cui ti vengono mostrati.
Pronto per iniziare?
Configura WhatsApp Coexistence in pochi minuti, non in mesi. L'app continua a funzionare sul telefono.
Inizia la prova gratuitaNessun addebito per 7 giorni. Annulla quando vuoi.