Manejo de Errores
Formato de respuesta de error y códigos de error comunes.
Formato de Error
Cada error incluye un mensaje error y un code:
Respuesta de error
{
"error": "Mensaje corto legible por humanos",
"code": "ERROR_CODE"
}Los errores de validación incluyen detalles adicionales:
Error de validación
{
"error": "Validación falló",
"code": "VALIDATION_ERROR",
"errors": [
{ "path": "/body/name", "message": "debe ser string" }
]
}Códigos de Error Comunes
| Status | Código | Descripción |
|---|---|---|
400 | VALIDATION_ERROR | Cuerpo de solicitud o parámetros inválidos. |
401 | UNAUTHORIZED | Clave de API ausente o inválida. |
402 | INSUFFICIENT_BALANCE | Créditos insuficientes para la operación. |
402 | PAYMENT_FAILED | Pago de activación de empresa falló. |
403 | FORBIDDEN | La empresa no está activa. |
404 | NOT_FOUND | El recurso no existe. |
409 | ALREADY_PROCESSED | Activación ya procesada. |
409 | CONVERSATION_CLOSED | La conversación ya no está activa. |
500 | INTERNAL_ERROR | Error inesperado del servidor. |
Manejando Errores 402
Si recibe INSUFFICIENT_BALANCE, el plan de la empresa no cubre la acción y no hay suficientes créditos prepagados. Compre créditos vía POST /api/companies/credits/purchase y reintente.
Mejores Prácticas
- Siempre verifique el campo
code, no el status HTTP, para manejo programático de errores. - Registre la respuesta de error completa para depuración.
- Presente el mensaje
errora los usuarios cuando sea apropiado. - Implemente lógica de reintento con backoff exponencial para errores
500.