Errores y límites
Cómo interpretar las respuestas de error de la API, qué significan los códigos por dominio y cómo manejar rate limits y reintentos.
Anatomía de un error
Todas las respuestas de error comparten la misma estructura. El campo code es un identificador estable con formato {dominio}_{número} que puedes usar para manejar cada caso de forma programática (no dependas del texto de message, que es legible pero puede cambiar).
{
"success": false,
"message": "API Key inválida o no existe.",
"status": 401,
"code": "auth_05"
}| Campo | Descripción |
|---|---|
success | false en todo error. |
message | Descripción legible en español. |
status | Código HTTP de la respuesta. |
code | Código estructurado {dominio}_{número}. |
request_id | UUID de seguimiento (presente en errores 500). Inclúyelo al contactar a soporte. |
Códigos HTTP
| HTTP | Significado | ¿Reintentar? |
|---|---|---|
200 | Éxito. | No aplica |
400 | Error de validación o de lógica de negocio (parámetros, saldo, mensaje). | No, corrige la petición. |
401 | API Key ausente, inválida o cuenta deshabilitada. | No, revisa tu llave. |
403 | La IP no está en la lista blanca de tu cuenta. | No, autoriza la IP en el panel. |
429 | Se excedió el rate limit. | Sí, con backoff. |
500 | Error interno del servidor. | Sí, con backoff; guarda el request_id. |
Códigos por dominio
El prefijo del code indica el área de la API donde ocurrió el error:
| Dominio | Área | Ejemplos |
|---|---|---|
auth_ | Autenticación y acceso | auth_04 (IP no autorizada, HTTP 403), auth_05 (API Key inválida, HTTP 401) |
sms_ | Envío de SMS | sms_02 (mensaje demasiado largo), sms_07 (créditos insuficientes), sms_402 (número no válido), sms_400 (parámetros inválidos), sms_11 (envío exitoso) |
verification_ | Generación de OTP (/otp/send) | verification_01 (código generado con éxito) y errores de generación |
validation_ | Verificación de OTP (/otp/verify) | código incorrecto, código expirado, o máximo de intentos por hora excedido |
rate_ | Rate limit | rate_01 (HTTP 429) |
server_ | Error interno | server_01 (HTTP 500) |
report_ | Reportes | report_400 (fechas inválidas), report_401 (sin resultados) |
credit_ | Créditos y saldo | credit_01 |
contact_ | Gestión de contactos | errores de alta y validación de contactos |
Cada endpoint documenta en el API Reference los códigos exactos que puede devolver, con su descripción. Por ejemplo, revisa los errores de /sms/send o de /otp/verify.
Errores frecuentes de SMS
// Créditos insuficientes
{ "success": false, "message": "insufficient_credits", "code": "sms_07" }
// Mensaje excede el límite de caracteres
{ "success": false, "message": "message_too_long", "code": "sms_02" }Antes de un envío grande, valida el saldo con /credits/consult para no fallar a mitad de la campaña con sms_07.
Rate limits
| Entorno | Límite | Al exceder |
|---|---|---|
| Producción | 100 mensajes/segundo | HTTP 429, code: rate_01 |
| Sandbox | 100 mensajes/día | HTTP 429, code: rate_01 |
Manejo de errores
Revisa success primero
Si success es false, no proceses la respuesta como éxito aunque el HTTP sea 200.
Ramifica por code, no por message
Usa el code estructurado (sms_07, auth_04, etc.) en tu lógica. El message es para logs y humanos.
Reintenta solo 429 y 500
Implementa reintentos con backoff exponencial únicamente en 429 y 500. Los 4xx restantes requieren corregir la petición.
Registra el request_id
En errores 500, guarda el request_id y compártelo con soporte para acelerar el diagnóstico.
Con esto puedes manejar cualquier respuesta de la API de forma robusta. Vuelve a la Guía rápida o explora el API Reference.