Códigos de error de la API

Referencia completa de cada código de error que la API puede devolver, con el status HTTP, cuándo ocurre y cómo recuperarse.

Envoltorio de error

Cada respuesta de error utiliza la misma estructura JSON canónica:

JSON
{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File is too large. Maximum size is 200 MB.",
    "details": { "max_bytes": 209715200, "received_bytes": 240000000 }
  }
}

Compruebe también siempre el status code HTTP — proporciona la categoría general (4xx = error del cliente, 5xx = error del servidor).

Referencia de códigos de error

CódigoHTTPCuándoCómo recuperarse
NO_FILE 400 Olvidó adjuntar un campo file, o el envío multipart estaba mal formado. Envíe la solicitud como multipart/form-data con un campo file. Para endpoints batch, use files[].
INVALID_FORMAT 400 Olvidó to_format, o la conversión solicitada no es compatible (p. ej. jpg → zzz). Pase un to_format válido. Consulte la referencia de convert para ver la lista completa de formatos soportados.
FILE_TOO_LARGE 413 El archivo subido supera el límite de tamaño (200 MB por defecto, menor para algunas herramientas de IA). Redimensione/comprima el archivo antes de subirlo, o divídalo en fragmentos más pequeños.
UNSUPPORTED_MIME 415 El tipo MIME del archivo no está en nuestra lista blanca (p. ej. .exe, .zip cuando no se esperan). Confirme el formato de su archivo. Consulte los formatos soportados en la página de inicio.
RATE_LIMITED 429 Alcanzó uno de los 5 niveles de rate limit. Respete el encabezado Retry-After. Vea los límites de tasa.
JOB_NOT_FOUND 404 El job_id no existe (error tipográfico, nunca creado) o ha caducado (los jobs se conservan 2 horas). Verifique que el job_id tenga exactamente 32 caracteres hexadecimales y que se creara en las últimas 2 horas.
JOB_EXPIRED 410 El job tiene más de 2 horas y el archivo convertido ha sido eliminado automáticamente. Vuelva a enviar la conversión. Descargue siempre el resultado con prontitud tras completarse el job.
CONVERSION_FAILED 500 El motor de conversión se ejecutó pero falló (p. ej. fuente corrupta, dependencias faltantes, excepción interna). Consulte error.message para los detalles. Pruebe con otro archivo. Reporte fallos repetidos vía /contact.
BATCH_TOO_LARGE 400 Su solicitud POST /api/v1/batch tenía más de 20 archivos. Divida su batch en fragmentos de ≤20 archivos.
NOT_FOUND 404 Endpoint desconocido o slug de herramienta desconocido (p. ej. /api/v1/tools/foobar). Revise la ortografía. Consulte /api/reference para ver los endpoints válidos.
NOT_IMPLEMENTED 501 El endpoint existe en nuestra documentación pero aún no está implementado en el servidor (p. ej. flip-image). Use una solución alternativa (p. ej. /api/v1/convert con img_rotate=flip-h) o espere a que la función esté disponible.
BANNED 403 Su IP provocó más de 10 rechazos de rate limit en 1 hora y ahora está bloqueada durante 24 horas. Espere a que caduque el bloqueo (vea Retry-After). Si es una IP compartida, contáctenos vía /contact.
INTERNAL_ERROR 500 Fallo inesperado del servidor. Debería ser raro. Reintente una vez tras unos segundos. Si persiste, repórtelo vía /contact con el encabezado X-Request-Id de la respuesta.

El encabezado X-Request-Id

Cada respuesta de la API (éxito o error) incluye un encabezado X-Request-Id. Al reportar un problema, incluya este ID para que podamos encontrar la solicitud en nuestros logs:

HTTP headers
X-Request-Id: 4f2dc3b5cc79fa57

Solicitar una función

0 / 2000