Códigos de error

Cuando una solicitud falla, la API devuelve una respuesta de error JSON con un code legible por máquinas y un message legible por humanos:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error"
  }
}

El campo code es estable y seguro para usar en la lógica de tu aplicación. El campo message puede cambiar con el tiempo y está destinado a registro y depuración.

Referencia de códigos de error

Código	Estado HTTP	Descripción	Reintentable	Resolución
UNAUTHORIZED	401	Token de autenticación faltante, inválido o expirado	No	Verifica que tu clave API sea válida y no haya expirado
KEY_EXPIRED	401	La clave API ha pasado su fecha de expiración	No	Crea una nueva clave API en el panel de control o mediante la API
FORBIDDEN	403	Autenticado pero no autorizado para este recurso	No	Solo puedes acceder a tus propios recursos
NOT_FOUND	404	El recurso solicitado no existe	No	Verifica que el ID del recurso sea correcto
VALIDATION_ERROR	400	El cuerpo de la solicitud no pasó la validación del esquema	No	Verifica que los campos requeridos y los tipos de datos coincidan con el esquema
INVALID_MIME_TYPE	400	El archivo subido tiene un tipo MIME no compatible	No	Usa un tipo de archivo compatible (PDF o DOCX)
FILE_TOO_LARGE	400	El archivo subido excede el límite de tamaño de 10 MB	No	Reduce el tamaño del archivo o divídelo en documentos más pequeños
MAX_KEYS_REACHED	400	Se alcanzó el máximo de 10 claves API activas	No	Revoca claves no utilizadas antes de crear nuevas
USAGE_LIMIT_EXCEEDED	429	Se alcanzó el límite mensual de extracciones	No	Mejora tu plan o espera al próximo período de facturación
INTERNAL_ERROR	500	Error inesperado del servidor	Sí	Reintenta con retroceso exponencial. Si persiste, contacta con soporte
NOT_CONFIGURED	501	Un servicio requerido del lado del servidor no está configurado	No	Contacta con soporte -- esto indica un problema de configuración del servidor
EXTRACTION_FAILED	502	El procesamiento de extracción con IA falló	Sí	Reintenta -- puede ser un problema transitorio. Verifica que el PDF sea válido y legible
EXTRACTION_PARSE_ERROR	502	La IA devolvió una respuesta que no pudo ser parseada como JSON	Sí	Reintenta -- la IA puede producir una salida válida en un intento posterior

Errores reintentables

Solo los siguientes códigos de error deben reintentarse:

• INTERNAL_ERROR -- Un fallo inesperado en el lado del servidor.
• EXTRACTION_FAILED -- El proceso de extracción con IA falló, a menudo debido a problemas transitorios.
• EXTRACTION_PARSE_ERROR -- La IA devolvió una salida mal formada que no pudo ser parseada.

Al reintentar, usa retroceso exponencial comenzando en 1 segundo, con un máximo de 3 reintentos:

Intento	Retardo
1er reintento	1 segundo
2do reintento	2 segundos
3er reintento	4 segundos

Si la solicitud sigue fallando después de 3 reintentos, registra el error y notifícalo al usuario o a tu sistema de monitoreo.

Para una guía completa sobre la implementación de lógica de reintentos, consulta Manejo de errores.

Resumen de códigos de estado HTTP

Estado	Significado
200	Éxito -- la solicitud se completó correctamente
400	Solicitud incorrecta -- error de validación, tipo de archivo inválido, archivo demasiado grande o límite de claves alcanzado
401	No autorizado -- la autenticación falló (token faltante, inválido o expirado)
403	Prohibido -- autenticado pero no autorizado para el recurso solicitado
404	No encontrado -- el recurso solicitado no existe
429	Demasiadas solicitudes -- se excedió el límite de uso mensual de extracciones
500	Error interno del servidor -- fallo inesperado en el lado del servidor
501	No implementado -- un servicio requerido del lado del servidor no está configurado
502	Bad Gateway -- la extracción o el parseo con IA falló