Errores y límites
La forma de los errores, qué código revisar en cada caso, el límite de requests por minuto y cuándo reintentar.
Forma de los errores
Todos los errores de la WABA API y de la API de CRM responden JSON con dos campos:
{
"error": "Too many requests",
"code": "RATE_LIMITED"
}codees estable: úsalo para decidir qué hacer.errores un mensaje para personas. Puede cambiar; no lo compares en tu código.
Algunos errores agregan campos con más contexto, por ejemplo leadIds cuando un teléfono coincide con varios leads, o hasDefault cuando una plantilla necesita un archivo en el encabezado.
Códigos generales
| HTTP | code | Causa |
|---|---|---|
| 400 | INVALID_REQUEST | Parámetro o body inválido: campo desconocido, tipo incorrecto o valor no permitido. error explica cuál. |
| 401 | AUTH_HEADER_MISSING, API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED | Problema con la clave. Ver Autenticación. |
| 403 | WABA_NOT_CONNECTED | WABA API sin ninguna línea de WhatsApp Business API activa. |
| 404 | ERR_NO_LEAD_FOUND, ERR_NO_CONTACT_FOUND… | No existe lo que buscas. |
| 409 | CONFLICT | La búsqueda por teléfono coincide con varios leads o contactos. |
| 429 | RATE_LIMITED | Superaste el límite de requests por minuto. |
| 500 | INTERNAL_ERROR | Error de Whapi. Reintenta más tarde. |
Los errores propios de WhatsApp empiezan con waba_ (por ejemplo, waba_session_window_expired). La referencia lista los que puede devolver cada operación.
Límite de requests
Cada empresa tiene un cupo de 300 requests por minuto en cada API: 300 para la WABA API y otras 300 para la API de CRM. Todas tus claves comparten el mismo cupo.
Si lo superas, la respuesta es 429 con code: RATE_LIMITED y el header Retry-After con los segundos que debes esperar.
La WABA API también puede responder 429 con code: waba_rate_limited. Ese límite no es de Whapi sino de Meta, por la cantidad de mensajes que envía tu línea. Espera unos minutos antes de reintentar.
Cuándo reintentar
| Respuesta | ¿Reintentar? |
|---|---|
429 | Sí, después del tiempo que indica Retry-After. |
500, 502, timeout o error de red | Sí, con esperas crecientes (por ejemplo, 2, 4 y 8 segundos). |
Otros 4xx | No. El request tiene un problema y volverá a fallar igual. |
Ten cuidado al reintentar POST /messages/send tras un timeout: si el primer intento llegó a Meta, el cliente recibirá el mensaje dos veces.
Compatibilidad
Las rutas no llevan número de versión. Whapi puede agregar campos nuevos a las respuestas y a los webhooks: tu integración debe ignorar los campos que no conozca, en lugar de fallar.
Los webhooks indican su formato en apiVersion (hoy 2026-06-15).