Errores
Cada error devuelve un cuerpo JSON junto con un código de estado HTTP.
Formato del error
Cada respuesta de error usa el mismo cuerpo JSON, sin importar el endpoint:
json
{
"statusCode": 400,
"error": "ValidationError",
"message": "channel is required",
"code": "optional_code",
"field": "channel"
}statusCode— El código de estado HTTP, repetido en el cuerpo.error— El nombre de la clase de error — úsalo para distinguir tipos de error en tu código.message— Una descripción legible de lo que salió mal.code— Un código estable y legible por máquina, presente solo cuando el error lo define (por ej.plan_limit).field— El campo de la solicitud implicado, presente solo en errores de validación a nivel de campo.
Los errores inesperados del servidor (500) nunca revelan detalles internos — el mensaje siempre está enmascarado:
json
{
"statusCode": 500,
"error": "InternalServerError",
"message": "Something went wrong"
}Códigos de estado
El campo error corresponde a una de las siguientes clases:
| Estado | Error | Significado |
|---|---|---|
400 | ValidationError | La solicitud no superó la validación — revisa message y field. |
401 | UnauthorizedError | Credenciales ausentes o inválidas. |
402 | PaymentRequiredError | Se alcanzó un límite del plan; code es plan_limit. Mejora el plan para continuar. |
403 | ForbiddenError | Autenticado, pero sin permiso para realizar esta acción. |
404 | NotFoundError | El recurso solicitado no existe. |
409 | ConflictError | La solicitud entra en conflicto con el estado actual del recurso. |
429 | Error | Demasiadas solicitudes — consulta Límite de solicitudes más abajo. |
500 | InternalServerError | Un error inesperado del servidor. El mensaje está enmascarado; revisa los registros del servidor para más detalles. |
Límite de solicitudes
La API permite 100 solicitudes por minuto en total, con límites más estrictos en algunos endpoints. Cuando una solicitud se limita, la API devuelve 429.
Una respuesta con límite de solicitudes usa la clase genérica Error en lugar de un tipo de error específico — su message indica cuánto esperar antes de reintentar:
json
{
"statusCode": 429,
"error": "Error",
"message": "Rate limit exceeded, retry in 1 minute"
}Espera y reintenta
No reintentes un 429 de inmediato. Espera y luego reintenta con retroceso exponencial y jitter.