Errores y límites

Maneja explícitamente los estados documentados, los límites del contrato y los reintentos idempotentes.

Estados HTTP

Estado	Significado	Acción
`200`	Operación aceptada, enviada o duplicada ya aceptada.	No repitas el efecto.
`400`	JSON incompleto, idempotencia inválida, plantilla inválida o destinatario prohibido.	Corrige la solicitud; no reintentes automáticamente.
`401`	API key ausente, inválida, regenerada o usada con otra conexión.	Revisa o regenera credencial.
`402`	Sin mensajes incluidos ni saldo de recarga.	Recarga mensajes o activa plan.
`404`	Conversación inexistente, bloqueada, ajena a la conexión o no elegible.	Marca conversación como no disponible.
`409`	La conexión de WhatsApp no está configurada correctamente.	Corrige la configuración de WhatsApp.
`413`	Cuerpo superior al límite.	Reduce el cuerpo.
`429`	Límite temporal alcanzado.	Respeta `Retry-After` y usa la misma clave de idempotencia.
`502`	Meta rechazó o no pudo completar el envío.	Reintento exponencial con la misma clave.

Ejemplos de error

402 Payment Required

{
  "error": "No quedan mensajes incluidos ni saldo de recargas.",
  "code": "CONNECT_MESSAGE_BALANCE_EXHAUSTED"


}

429 Too Many Requests

{
  "error": "Límite de 5 plantillas por minuto alcanzado para esta conexión.",
  "code": "CONNECT_TEMPLATE_RATE_LIMIT"
}

502 Bad Gateway

{
  "error": "Mensaje devuelto por Meta",
  "code": "CONNECT_META_SEND_FAILED"
}

Para /reply puede devolverse CONNECT_REPLY_FAILED; para /template, CONNECT_TEMPLATE_FAILED.

Límites

Texto: máximo 4,000 caracteres.
Idempotency-Key: 8 a 200 caracteres.
Cuerpo general de las rutas: 2 MiB.
Plantillas: máximo 5 por minuto por conexión.
Componentes de plantilla: máximo 20.
URL del webhook: máximo 2,000 caracteres.
Webhook: respuesta antes de 15 segundos.

La plataforma aplica protecciones adicionales contra abuso que pueden ajustarse sin previo aviso para mantener la disponibilidad.

Reintentos

El webhook entrante no se reintenta automáticamente en v1. Para llamadas de salida, reintenta errores transitorios 429 y 5xx con espera exponencial y jitter, usando la misma Idempotency-Key.

Espera sugerida

1 s, 2 s, 4 s, 8 s, 16 s + jitter

Máximo recomendado: 5 intentos para errores transitorios. No reintentes automáticamente 400, 401, 402 o 404 sin corregir la causa.

Consumo

Plan gratuito: 1,000 mensajes al mes.
Plan activo: 5,000 mensajes al mes.
El contador mensual usa periodos YYYY-MM en UTC.
Las recargas se consumen después del incluido y no caducan.
Sin plan activo, el saldo de recarga no habilita por sí solo el relay de pago.
El evento entrante se reserva antes de llamar al webhook.
Un fallo del webhook no devuelve ese mensaje al saldo.
Un fallo de salida hacia Meta sí devuelve la reserva correspondiente.