Respuestas y errores
Toda llamada a la API responde con un objeto JSON con la propiedad success indicando
si el envío fue aceptado. Esta página documenta el formato de respuestas exitosas, los códigos de
error posibles y cómo manejarlos en tu integración.
Respuesta exitosa
Cuando el mensaje fue aceptado por Meta, recibes HTTP 200 OK con el wamid
(WhatsApp Message ID) que te servirá para trackear el estado del mensaje en tu webhook.
{
"success": true,
"messages": [
{ "id": "wamid.HBgMNTkzOTk5OTk5OTk5FQIAERgS..." }
]
}| Campo | Tipo | Descripción |
|---|---|---|
success |
boolean | Siempre true en respuestas exitosas. |
messages |
array | Array con un objeto por mensaje enviado (normalmente uno). |
messages[].id |
string | El wamid del mensaje. Comienza con wamid. y es único globalmente. |
El wamid es tu llave para todo. Guárdalo siempre en tu base de datos.
Te llegarán los estados sent, delivered, read, failed
en tu webhook y se identifican por este mismo ID.
Estados posibles del mensaje
Después del envío, recibirás actualizaciones de estado en tu webhook (ver cómo configurar tu webhook). Los estados son:
| Estado | Significado | Cuándo llega |
|---|---|---|
| sent | Mensaje aceptado por Meta y entregado a su sistema | Inmediatamente tras el POST exitoso. |
| delivered | Llegó al dispositivo del cliente (un check) | Cuando el cliente recibe el mensaje en su teléfono. |
| read | El cliente abrió el chat y lo vio (dos checks azules) | Sólo si el cliente tiene activadas las confirmaciones de lectura. |
| failed | Falló la entrega final por el lado del cliente | Cuando el número no existe, no usa WhatsApp, te bloqueó, etc. |
Errores
Cuando algo falla, recibes HTTP 4xx o 5xx con un JSON con "success": false:
{
"success": false,
"error": "low_quality",
"message": "The number does not have a high reputation. Sending has been blocked."
}| Campo | Tipo | Descripción |
|---|---|---|
success | boolean | Siempre false en errores. |
error | string | Código corto del error, útil para detectarlo programáticamente. |
message | string | Descripción humana del error en inglés. |
details | object | Información adicional cuando aplica (ej: detalle de Meta). |
Códigos de error frecuentes
| HTTP | Código error | Descripción | Cómo resolver |
|---|---|---|---|
| 400 | invalid_payload |
JSON mal formado o falta un campo requerido. | Valida tu JSON. Revisa messaging_product, to y type. |
| 400 | invalid_recipient |
Número destino inválido o no es un número WhatsApp activo. | Confirma formato E.164 sin +. Probar con un número que sepas que tiene WhatsApp. |
| 401 | unauthorized |
Token Bearer ausente o inválido. | Verifica header Authorization: Bearer ... y que el token esté completo. |
| 403 | forbidden_tid |
El token no pertenece al tid de la URL. |
El tid y el código de seguridad deben ser de la misma línea. |
| 403 | low_quality |
Reputación del número en nivel bajo. Envíos bloqueados. | Ver guía de reputación. Pausa envíos masivos. |
| 404 | tid_not_found |
El tid no existe en el sistema. |
Revisa el ID en tu panel. |
| 422 | template_not_approved |
La plantilla no existe o no está aprobada. | Confirma nombre exacto e idioma. Revisa estado en panel. |
| 422 | outside_24h_window |
Intentaste enviar texto libre fuera de la ventana de 24h. | Usa una plantilla aprobada para reabrir conversación. |
| 422 | media_url_invalid |
La URL de la imagen / documento no es accesible públicamente. | La URL debe ser HTTPS, pública y devolver el archivo (no un HTML wrapper). |
| 429 | rate_limited |
Excediste el límite de mensajes por segundo. | Implementa retry con backoff exponencial. Reduce cadencia. |
| 500 | internal_error |
Error inesperado del gateway. | Reintenta. Si persiste, contacta soporte con el timestamp. |
| 502 | meta_unavailable |
Meta WhatsApp Cloud API no respondió. | Reintenta con backoff. Verifica metastatus.com. |