Errori

Gli errori hanno sempre lo stesso formato: un code stabile, il messaggio in italiano e in inglese e un request_id da citare se contatti l'assistenza.

HTTP/1.1 422
{
  "error": {
    "code": "outside_24h_window",
    "message": "Sono passate più di 24 ore dall'ultimo messaggio del destinatario: ...",
    "message_en": "More than 24 hours since the recipient's last message: use an approved template.",
    "request_id": "req_3f9a...",
    "details": { "meta_code": 131047 }
  }
}

Risposta 202: esito da confermare

Se Meta non risponde in tempo non sappiamo se il messaggio è partito. Restituiamo 202 con stato unknown: non rimandare, lo stato definitivo arriva via webhook o con GET /v1/messages/{id}.

Errori della piattaforma

Codice	HTTP	Significato
`unauthorized`	401	Chiave mancante, revocata o non valida.
`validation_error`	422	Dati della richiesta non validi: il campo è indicato in details.
`not_found`	404	Cliente, messaggio o template inesistente (o di un altro account).
`forbidden`	403	Operazione non consentita, per esempio chiave sandbox su un’operazione live o account non approvato.
`conflict`	409	Stato non compatibile, per esempio Idempotency-Key riusata con un corpo diverso.
`customer_not_connected`	409	Il cliente non ha ancora collegato il numero: manda il link di onboarding.
`customer_not_active`	409	Attivazione non completata: manca il collegamento, il metodo di pagamento su WhatsApp Manager o il pagamento della fee di attivazione.
`customer_suspended`	403	Cliente in pausa o bloccato: invii sospesi. Il motivo è nel messaggio.
`marketing_paused`	403	Template marketing in pausa per qualità bassa del numero (RED). Utility e autenticazione continuano.
`template_not_approved`	422	Il template non è approvato per questa lingua.
`template_sandbox_only`	422	Template creato in sandbox: crealo con una chiave live per sottoporlo a Meta.
`payment_overdue`	402	Riepiloghi De Palma Labs scaduti da oltre 15 giorni: nuovi collegamenti sospesi fino al pagamento.
`daily_limit`	429	Limite giornaliero di invii del cliente raggiunto.
`rate_limited`	429	Troppe richieste: rispetta l’header Retry-After.
`platform_paused`	503	Invii sospesi temporaneamente dalla piattaforma. Riprova più tardi.
`meta_error`	422	Errore di Meta non tradotto: vedi details.meta_code. Sull’invio, se Meta non risponde ricevi 202 con stato unknown; sui template, 502.
`internal_error`	500	Errore interno: riprova con la stessa Idempotency-Key e, se persiste, scrivici con il request_id.

Errori di WhatsApp tradotti

I codici di Meta più frequenti vengono tradotti in un codice leggibile; quello originale resta in details.meta_code.

Codice	HTTP	Meta	Cosa significa
`outside_24h_window`	422	131047	Sono passate più di 24 ore dall'ultimo messaggio del destinatario: puoi scrivergli solo con un template approvato.
`recipient_unreachable`	422	131026	Messaggio non consegnabile: il numero non usa WhatsApp, non ha accettato i termini aggiornati o ha una versione troppo vecchia.
`meta_payment_issue`	402	131042	Il cliente non ha un metodo di pagamento valido su WhatsApp Manager: invii bloccati finché non lo aggiunge.
`template_param_mismatch`	422	132000	Il numero di variabili non corrisponde a quelle del template.
`template_not_found`	422	132001	Template inesistente o non approvato per questa lingua.
`template_text_too_long`	422	132005	Il testo del template con le variabili supera la lunghezza massima.
`template_policy`	422	132007	Il contenuto del template viola le policy di Meta.
`template_param_format`	422	132012	Formato delle variabili non valido per questo template.
`template_paused`	422	132015, 132016	Template messo in pausa o disattivato da Meta per bassa qualità.
`pair_rate_limit`	429	131056	Troppi messaggi allo stesso destinatario in poco tempo. Riprova più tardi.
`meta_rate_limit`	429	130429, 80007	Limite di velocità di Meta raggiunto per questo numero. Riprova tra poco.
`spam_rate_limit`	429	131048	Meta ha limitato gli invii di questo numero per segnalazioni di spam. Riduci i volumi e verifica l'opt-in.
`ecosystem_limit`	422	131049	Meta non ha consegnato il marketing per tutelare l'esperienza del destinatario.
`account_locked`	403	131031	L'account WhatsApp del cliente è bloccato da Meta.
`unsupported_type`	422	131051	Tipo di messaggio non supportato.
`media_error`	422	131052, 131053	Il file indicato non è scaricabile o il formato non è supportato da WhatsApp.
`phone_not_registered`	409	133010	Il numero del cliente non risulta registrato sulla Cloud API.
`policy_block`	403	368	Il numero è temporaneamente bloccato da Meta per violazione delle policy.
`token_invalid`	409	190	L'autorizzazione del cliente non è più valida: serve un nuovo collegamento.
`invalid_parameter`	422	131008, 131009, 100	Parametro mancante o non valido nella richiesta a WhatsApp.