Solución de Problemas

Referencia de Errores

Una guía completa para manejar errores de API con gracia. Utilizamos códigos HTTP estándar mejorados con contexto JSON detallado.

Formato de Error Estándar

Todas las respuestas de error devuelven un objeto JSON estandarizado. El campo detail contiene información estructurada para ayudarte a depurar o mostrar mensajes amigables para el usuario.

error-structure.json

{
  "detail": {
    "error": "INVALID_FILE_TYPE",
    "message": "Tipo de archivo no compatible. Sube un archivo PDF, DOCX o TXT.",
    "suggestion": "Convierte tu archivo a PDF, DOCX o TXT e inténtalo de nuevo.",
    "severity": "medium",
    "technical_details": "Tipo MIME detectado: application/octet-stream"
  }
}

Referencia de Errores

Errores de Validación

100-199

VALIDATION_ERROR

Fallo general de validación.

INVALID_INPUT

El formato de entrada proporcionado es incorrecto.

MISSING_FIELD

Falta un campo obligatorio en la carga útil.

Errores de Autenticación

200-299

AUTH_ERROR

La autenticación falló.

INVALID_API_KEY

La clave API proporcionada no es válida o está deshabilitada.

API_KEY_EXPIRED

La clave API ha caducado.

INSUFFICIENT_PERMISSIONS

La clave API no tiene permiso para acceder a ese recurso.

Errores de Carga de Archivos

300-399

INVALID_FILE_TYPE

Solo se admiten archivos PDF, DOCX y TXT.

FILE_TOO_LARGE

El archivo excede el límite de tamaño máximo (5 MB).

FILE_CORRUPTED

El archivo no se pudo leer o está dañado.

PDF_QUALITY_ISSUE

El PDF contiene imágenes escaneadas o texto ilegible.

Límite de Velocidad

400-499

RATE_LIMIT_EXCEEDED

Demasiadas solicitudes en un corto período.

QUOTA_EXCEEDED

Se ha alcanzado la cuota mensual de la API.

Errores del Servidor

500-799

PARSING_FAILED

El motor de análisis no pudo procesar el documento.

AI_PROCESSING_FAILED

El modelo de IA encontró un error al analizar el contenido.

INTERNAL_ERROR

Ocurrió un error inesperado del servidor interno.

SERVICE_UNAVAILABLE

El servicio no está disponible temporalmente.

¿Necesitas ayuda para depurar?

Si encuentras un INTERNAL_ERROR de manera constante, contacta al soporte con el ID de la solicitud y la marca de tiempo. Ten en cuenta que AI_PROCESSING_FAILED puede ocurrir si el contenido de entrada es demasiado ambiguo o viola las políticas de seguridad.