Errores y límites

Los códigos de error de la API de Yolani, las dos respuestas con otro formato (exceso de peticiones y suscripción inactiva), los límites de peticiones con sus headers y cómo reintentar.

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.

HTTPCódigoQué pasó
400VALIDATION_ERRORFalta un campo requerido, tiene un valor que no se acepta o el id de la ruta no es un número
400INTERNAL_ERROREl cuerpo no es un JSON válido (llega con este código; el message dice dónde está el error)
400NO_ASSISTANTQuisiste encender al agente y tu cuenta no tiene ningún agente activo
401MISSING_API_KEYNo mandaste el header Authorization: Bearer ... (va con "Bearer" así, con B mayúscula)
401INVALID_API_KEYEl token no existe, fue revocado o ya expiró
403MODULE_NOT_ENABLEDTu plan no incluye la API
403INSUFFICIENT_SCOPELa API key no tiene el permiso que pide ese endpoint
404NOT_FOUNDEl contacto, la conversación o el webhook no existe o no es de tu cuenta
404STAGE_NOT_FOUNDLa etapa a la que quieres mover la conversación no existe o está inactiva
409SUBSCRIPTION_LIMITTu cuenta ya tiene 100 webhooks dados de alta por la API
413MEDIA_TOO_LARGEEl archivo de media_url pasa de 15 MB
422MEDIA_DOWNLOAD_FAILEDNo se pudo descargar media_url
422WHATSAPP_NUMBER_NOT_REGISTEREDEse número no tiene WhatsApp
429RATE_LIMIT_PUBLIC_APISuperaste el límite de peticiones de tu cuenta (ver abajo)
500INTERNAL_ERRORError 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ódigoQué pasó
TRIAL_EXPIREDTerminó tu periodo de prueba
INACTIVE_SUBSCRIPTIONTu suscripción está vencida, cancelada o con un pago pendiente
ACCOUNT_SUSPENDEDTu cuenta está suspendida por falta de pago
ADMIN_GRANT_EXPIREDTerminó un periodo de cortesía
SUB_ACCOUNT_SUSPENDEDTu 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ímiteCuántoSe cuenta por
De tu cuenta300 peticiones por minuto (ventana móvil de 60 segundos)Empresa: todas tus API keys suman al mismo cupo
General de la plataforma800 peticiones cada 15 minutosDirecció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:

HeaderDe qué límiteDescripción
X-RateLimit-BucketCuentapublic_api
X-RateLimit-LimitCuenta300
X-RateLimit-RemainingCuentaPeticiones que te quedan en el último minuto
RateLimit-PolicyIP800;w=900 (800 peticiones en 900 segundos)
RateLimit-LimitIP800
RateLimit-RemainingIPPeticiones que te quedan en la ventana de 15 minutos
RateLimit-ResetIPSegundos para que esa ventana vuelva a empezar
Retry-AfterLos dosSegundos 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 429 o un 5xx, espera (respeta Retry-After) y reintenta, duplicando la espera en cada intento.
  • No dupliques mensajes: manda client_request_id al enviar texto; si reintentas, no sale dos veces.
  • Pagina: pide solo lo que necesitas con limit y offset.
  • 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');
}