Formato de los errores
Casi todos los errores llegan así, con un código fijo que puedes leer desde tu código y un mensaje para humanos:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "phone o email requerido"
}
}
Decide con error.code (o con el código HTTP), no con el texto de message: el texto puede cambiar.
| HTTP | Código | Qué pasó |
|---|---|---|
| 400 | VALIDATION_ERROR | Falta un campo requerido, tiene un valor que no se acepta o el id de la ruta no es un número |
| 400 | INTERNAL_ERROR | El cuerpo no es un JSON válido (llega con este código; el message dice dónde está el error) |
| 400 | NO_ASSISTANT | Quisiste encender al agente y tu cuenta no tiene ningún agente activo |
| 401 | MISSING_API_KEY | No mandaste el header Authorization: Bearer ... (va con "Bearer" así, con B mayúscula) |
| 401 | INVALID_API_KEY | El token no existe, fue revocado o ya expiró |
| 403 | MODULE_NOT_ENABLED | Tu plan no incluye la API |
| 403 | INSUFFICIENT_SCOPE | La API key no tiene el permiso que pide ese endpoint |
| 404 | NOT_FOUND | El contacto, la conversación o el webhook no existe o no es de tu cuenta |
| 404 | STAGE_NOT_FOUND | La etapa a la que quieres mover la conversación no existe o está inactiva |
| 409 | SUBSCRIPTION_LIMIT | Tu cuenta ya tiene 100 webhooks dados de alta por la API |
| 413 | MEDIA_TOO_LARGE | El archivo de media_url pasa de 15 MB |
| 422 | MEDIA_DOWNLOAD_FAILED | No se pudo descargar media_url |
| 422 | WHATSAPP_NUMBER_NOT_REGISTERED | Ese número no tiene WhatsApp |
| 429 | RATE_LIMIT_PUBLIC_API | Superaste el límite de peticiones de tu cuenta (ver abajo) |
| 500 | INTERNAL_ERROR | Error de nuestro lado; reintenta más tarde |
Los errores de plantillas (TEMPLATE_NOT_FOUND, WHATSAPP_API_NOT_CONFIGURED...) están en Plantillas.
Un envío que falla no siempre es un error:
Si el mensaje se pudo guardar pero el canal no lo aceptó, la API responde 201 con "status": "failed" en vez de un error. Revisa siempre el status de la respuesta al enviar. Ver Mensajes.
Suscripción inactiva
Los endpoints que envían o abren algo (POST /conversations, POST /conversations/:id/messages y POST /conversations/:id/messages/template) piden además una suscripción vigente. Si tu prueba terminó o tu cuenta está suspendida, responden 403 con otra forma: error es el texto y code va afuera.
{
"error": "El periodo de prueba ha expirado",
"code": "TRIAL_EXPIRED",
"requiresPayment": true
}
| Código | Qué pasó |
|---|---|
TRIAL_EXPIRED | Terminó tu periodo de prueba |
INACTIVE_SUBSCRIPTION | Tu suscripción está vencida, cancelada o con un pago pendiente |
ACCOUNT_SUSPENDED | Tu cuenta está suspendida por falta de pago |
ADMIN_GRANT_EXPIRED | Terminó un periodo de cortesía |
SUB_ACCOUNT_SUSPENDED | Tu cuenta la administra una agencia y la pausó |
Las lecturas y los contactos siguen funcionando. Para reactivar los envíos, renueva tu plan en Suscripción.
Límites de peticiones
Hay dos límites y cuentan al mismo tiempo:
| Límite | Cuánto | Se cuenta por |
|---|---|---|
| De tu cuenta | 300 peticiones por minuto (ventana móvil de 60 segundos) | Empresa: todas tus API keys suman al mismo cupo |
| General de la plataforma | 800 peticiones cada 15 minutos | Dirección IP desde la que llamas |
Si todas tus llamadas salen de un mismo servidor, el que vas a tocar primero es el de 800 cada 15 minutos (en promedio, unas 53 por minuto). Reparte las ráfagas grandes en el tiempo.
Headers
Cada respuesta trae el estado de los dos:
| Header | De qué límite | Descripción |
|---|---|---|
X-RateLimit-Bucket | Cuenta | public_api |
X-RateLimit-Limit | Cuenta | 300 |
X-RateLimit-Remaining | Cuenta | Peticiones que te quedan en el último minuto |
RateLimit-Policy | IP | 800;w=900 (800 peticiones en 900 segundos) |
RateLimit-Limit | IP | 800 |
RateLimit-Remaining | IP | Peticiones que te quedan en la ventana de 15 minutos |
RateLimit-Reset | IP | Segundos para que esa ventana vuelva a empezar |
Retry-After | Los dos | Segundos que debes esperar. Solo viene en las respuestas 429 |
En una respuesta 401 (key faltante o inválida) verás X-RateLimit-Bucket: api_general con un límite de 5000: es el contador general de la plataforma, no el de tu cuenta.
Al superar un límite
Recibes 429, también con otra forma. Si fue el límite de tu cuenta:
{
"success": false,
"code": "RATE_LIMIT_PUBLIC_API",
"error": "Has superado el limite configurado para tu plan. Espera un momento.",
"bucket": "public_api",
"limit": 300,
"windowMs": 60000
}
Si fue el límite por IP:
{
"success": false,
"error": "Demasiadas solicitudes, intenta de nuevo en unos minutos."
}
En los dos casos, espera los segundos de Retry-After antes de volver a intentar.
¿Necesitas más volumen?:
Si tu integración necesita un límite mayor en tu cuenta, escríbenos y lo ajustamos.
Buenas prácticas
- Reintenta con espera creciente: ante un
429o un5xx, espera (respetaRetry-After) y reintenta, duplicando la espera en cada intento. - No dupliques mensajes: manda
client_request_idal enviar texto; si reintentas, no sale dos veces. - Pagina: pide solo lo que necesitas con
limityoffset. - Usa webhooks en lugar de preguntar cada minuto: para enterarte de los mensajes nuevos, suscríbete a
message.received(ver Webhooks).
// Reintento con espera creciente que respeta Retry-After
async function llamarYolani(url, opciones, intentos = 4) {
for (let i = 0; i < intentos; i++) {
const res = await fetch(url, opciones);
if (res.status !== 429 && res.status < 500) return res;
const espera = Number(res.headers.get('Retry-After')) || 2 ** i;
await new Promise((r) => setTimeout(r, espera * 1000));
}
throw new Error('La API de Yolani no respondió después de varios intentos');
}