Errores, estados y límites
Ciclo de vida de un mensaje
Todo mensaje (individual o de broadcast) avanza por estos estados, visibles en el portal (sección Mensajes):
| Estado | Significado |
|---|---|
pending |
Recibido por Arplyx, esperando que el worker lo procese. |
queued |
En cola para salir al canal. Si hubo un fallo transitorio, queda acá entre reintentos. |
sent |
Entregado al proveedor del canal (Meta o WhatsApp Direct). |
delivered |
El proveedor confirmó entrega en el dispositivo del destinatario. |
read |
El destinatario lo leyó (cuando el canal lo informa). |
failed |
Falló de forma definitiva: se agotaron los reintentos o el error no es recuperable. El detalle del mensaje muestra el código y la descripción del último error. |
Reintentos: los errores transitorios (problemas de red, 5xx del proveedor, rate limit) se reintentan automáticamente con backoff exponencial, hasta 5 intentos por defecto. Los errores permanentes (número inválido, cuenta desvinculada, credenciales rechazadas) marcan el mensaje failed sin reintentar.
Para Meta Official
Los estados delivered y read llegan por el webhook de tu app de Meta. Si no configuraste el webhook, los mensajes quedan en sent. Ver el paso 6 de la guía Meta.
Catálogo de errores HTTP
Todas las respuestas de error tienen un campo error; algunas agregan message o campos extra.
| Status | error |
Cuándo |
|---|---|---|
| 400 | validation_error |
El payload no pasa la validación. El cuerpo incluye details: una lista de { "path": "campo.afectado", "message": "..." } por cada problema. |
| 401 | Missing x-api-key header / Invalid API key |
Falta la clave, es inválida o fue revocada. |
| 409 | conflict |
El externalId ya existe con un payload distinto. Elegí otro externalId o repetí el payload original. |
| 422 | invalid_whatsapp_account |
El whatsappAccountId no existe, no es tuyo, o su tipo no coincide con el channel (ej.: cuenta Direct con canal whatsapp_meta). |
| 403 | templates_not_available |
Intentaste enviar una plantilla en el plan Free. El envío de plantillas (proactivo) está disponible desde el plan Starter. |
| 429 | quota_exceeded |
Cuota mensual agotada. El cuerpo incluye limit, used y resetsAt (cuándo se renueva: primer día del mes, UTC). |
| 500 | Internal server error |
Error inesperado de Arplyx. Reintentá con el mismo externalId (es seguro por idempotencia); si persiste, contactanos. |
Ejemplo de validation_error:
{
"error": "validation_error",
"details": [
{ "path": "to.phoneE164", "message": "Invalid E.164 phone number" }
]
}
Los errores exclusivos de broadcast (lista vacía, plan sin broadcasts, etc.) están en Broadcasts por API.
Cuotas y límites por plan
| Plan | Mensajes/mes | Cuentas WhatsApp | Retención de historial | Broadcasts |
|---|---|---|---|---|
| Free | 500 | 1 | 3 días | No |
| Starter | 2.000 | 1 | 30 días | No |
| Basic | 10.000 | 3 | 30 días | Sí |
| Pro | 20.000 | 5 | 30 días | Sí |
- La cuota es compartida entre la API, el portal y los broadcasts: todo mensaje individual cuenta.
- Se renueva el día 1 de cada mes (UTC). El cuerpo del error
429te dice exactamente cuándo (resetsAt). - Tope adicional por broadcast: 5.000 destinatarios.
ttlSecondsse recorta a la retención del plan (en Free, un mensaje no puede vivir más de 3 días en cola).
¿Necesitás más volumen? Escribinos a info@arplyx.com.