Codigos de Error

Comprendiendo las respuestas de error de la API y como manejarlas.

Descripcion General

La API devuelve respuestas de error estandarizadas con codigos de error especificos para ayudarte a identificar y resolver problemas rapidamente.

Formato de Respuesta de Error

{
  "status": "error",
  "error": {
    "code": "AUTH_1001",
    "message": "Credenciales de autenticacion faltantes",
    "details": "Los campos 'username' y 'password' son requeridos",
    "timestamp": "2025-12-22T10:30:00Z"
  }
}

Errores de Autenticacion (1000-1099)

Codigo	HTTP	Mensaje	Solucion
`AUTH_1001`	401	Credenciales de autenticacion faltantes	Incluye usuario y contrasena en la solicitud
`AUTH_1002`	401	Usuario o contrasena invalidos	Verifica que las credenciales sean correctas
`AUTH_1003`	403	Cuenta temporalmente bloqueada	Espera antes de reintentar o contacta con soporte

Errores de Cuota (1100-1199)

Codigo	HTTP	Mensaje	Solucion
`QUOTA_1101`	403	Cuota de API insuficiente	Compra mas creditos o verifica la cuota
`QUOTA_1102`	429	Cuota de API excedida	Espera la renovacion de cuota o mejora el plan

Errores de Validacion (2000-2099)

Codigo	HTTP	Mensaje	Solucion
`VAL_2001`	400	Ningun archivo subido	Incluye un archivo en la solicitud
`VAL_2002`	400	Formato de archivo invalido	Usa formatos soportados: PDF, PNG, JPG, WEBP
`VAL_2003`	400	Multiples archivos PDF no permitidos	Sube un solo PDF o varias imagenes
`VAL_2004`	400	PDF e imagenes no pueden mezclarse	Sube PDF o imagenes, no ambos

Errores de Procesamiento (3000-3099)

Codigo	HTTP	Mensaje	Solucion
`PROC_3001`	500	Fallo en el procesamiento del documento	Verifica la calidad de la imagen, reintenta
`PROC_3006`	504	Timeout en el procesamiento	Reduce el tamano del archivo o divide en multiples solicitudes

Errores del Servidor (5000-5099)

Codigo	HTTP	Mensaje	Solucion
`SRV_5001`	500	Error interno del servidor	Reintenta, contacta con soporte si persiste
`SRV_5002`	503	Servicio temporalmente no disponible	Espera y reintenta con backoff exponencial

Mejores Practicas de Manejo de Errores

Recomendaciones

Siempre verifica el campo status - Las respuestas exitosas tienen "status": "success"
Implementa logica de reintentos para errores transitorios (5xx) con backoff exponencial
Registra codigos de error para depuracion y monitoreo
Muestra mensajes amigables basados en los codigos de error