Errores y límites

Los errores siempre llegan con esta estructura:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "phone o email requerido"
  }
}

HTTP	Código	Descripción
400	`VALIDATION_ERROR`	Falta un campo requerido o tiene formato inválido
401	`MISSING_API_KEY`	No enviaste el header `Authorization`
401	`INVALID_API_KEY`	Token inválido, revocado o expirado
403	`MODULE_NOT_ENABLED`	Tu plan no incluye la API pública
403	`INSUFFICIENT_SCOPE`	La API key no tiene el permiso necesario
404	`NOT_FOUND`	El recurso no existe o no pertenece a tu cuenta
404	`TEMPLATE_NOT_FOUND`	La plantilla no existe en tu WABA
400	`TEMPLATE_NOT_APPROVED`	La plantilla existe pero Meta aún no la aprueba
400	`TEMPLATE_PARAMS_MISMATCH`	Faltan o sobran valores para las variables de la plantilla
413	`MEDIA_TOO_LARGE`	El archivo supera los 15 MB
422	`MEDIA_DOWNLOAD_FAILED`	No se pudo descargar el `media_url`
429	`RATE_LIMIT_PUBLIC_API`	Superaste el límite de peticiones
500	`INTERNAL_ERROR`	Error interno; reintenta más tarde

Rate limiting

Por defecto cada cuenta puede hacer 300 peticiones por minuto a la API. Cada respuesta incluye headers para monitorear tu consumo:

Header	Descripción
`X-RateLimit-Limit`	Límite de tu ventana actual
`X-RateLimit-Remaining`	Peticiones restantes
`Retry-After`	Segundos a esperar (solo en respuestas 429)

Al superar el límite recibes 429:

{
  "success": false,
  "code": "RATE_LIMIT_PUBLIC_API",
  "error": "Has superado el limite configurado para tu plan. Espera un momento."
}

¿Necesitas más volumen?:

Si tu integración requiere un límite mayor, contáctanos y lo ajustamos para tu cuenta.

Reintentos con espera exponencial: ante 429 o 5xx, espera y reintenta (respeta Retry-After)
Idempotencia: usa client_request_id al enviar mensajes para evitar duplicados
Paginación: no pidas más de lo que necesitas; usa limit y offset
Webhooks en lugar de polling: para reaccionar a mensajes nuevos, suscríbete a message.received en lugar de consultar la API repetidamente