Códigos de error de la API de EnConvert#

Esta referencia enumera todos los códigos de estado HTTP y mensajes de error que devuelve la API de EnConvert, desde 200 OK para conversiones síncronas y 202 Accepted para trabajos asíncronos y por lotes, hasta las respuestas de error documentadas a continuación. Cada sección de error enumera las cadenas de mensaje exactas, la condición que activa cada una, y cómo corregir la solicitud. Los cuerpos de error no tienen todos la misma forma: existen seis, y la sección Formato de respuesta de error muestra cada una.

Un trabajo que falla después de haber sido aceptado no es un error HTTP. El 202 se mantiene y el fallo aparece en la carga de estado del trabajo cuando lo consultas, tal como se describe en Trabajos síncronos y asíncronos.

Códigos de estado HTTP#

Formato de respuesta de error#

Existen seis formas de cuerpo. Cuál recibes depende de dónde ocurrió el fallo, no solo del código de estado, así que comprueba el tipo de detail antes de leerlo.

1. detail de tipo cadena. El caso común, y la única forma que ven la mayoría de las integraciones.

{
    "detail": "Authentication required"
}

2. detail de tipo objeto. El 413 por tamaño de archivo del plan. El objeto estructurado es el valor de detail, así que lee body.detail.max_size, no body.max_size. Consulta 413 Payload Too Large.

{
    "detail": {
        "error": "File too large",
        "file_size": 10485760,
        "max_size": 5242880,
        "tier": "free",
        "key_type": "private"
    }
}

3. detail de tipo array más errors. La validación de esquema (422) devuelve ambos: detail es la salida sin procesar del validador y errors es un array paralelo de cadenas legibles por personas. Consulta 422 Unprocessable Entity.

4. Envoltorio de conversión tipificado. {"error", "code", "detail"}, con un code legible por máquina. Solo lo emiten los tres endpoints V1 de conversión de URL. Consulta Errores de conversión del navegador.

5. Excepción no controlada. Un 500 que no proviene de un conversor no tiene detail en absoluto:

{
    "error": "Internal server error",
    "event_id": "a1b2c3d4"
}

6. Tiempo de espera de solicitud del gateway. El propio presupuesto de 300 segundos del gateway produce un 504 sin detail y sin code:

{
    "error": "Request timeout"
}

400 Bad Request#

Se devuelve cuando la solicitud contiene parámetros inválidos, campos faltantes o datos malformados.

Validación de entrada#

Validación de lote y modo#

Validación de autenticación, cookies y encabezados#

Seguridad de URL (SSRF)#

Todos los endpoints basados en URL examinan la url de destino antes de obtenerla. Estos mensajes se devuelven como 400 cuando la URL no es una dirección pública http(s).

Validación de opciones de renderizado#

Errores de sitemap y rastreo#

Errores de contenido de conversión#

401 Unauthorized#

Se devuelve cuando falta la autenticación o es inválida.

402 Payment Required#

Se devuelve cuando se supera un límite de uso. La división entre 402 y 403 no es simétrica y suele confundir. Toda condición de cuota responde 402, igual que un endpoint V2 desactivado en tu plan. Las restricciones de funciones V1 responden 403 (async, webhooks, salida ZIP, autenticación básica, lotes). La limitación de tasa es un mecanismo aparte que responde 429, nunca 402.

Quedarse sin créditos mensuales de IA no produce un 402. La extracción de esquema recurre al resultado heurístico y CSS, y la solicitud sigue teniendo éxito. Las asignaciones, los precios y qué cuenta como una operación están en Límites de tasa y cuotas.

403 Forbidden#

Se devuelve cuando se deniega el acceso debido a restricciones de tipo de clave, dominio, función V1 del plan o endpoint. Las restricciones de endpoints V2 son la excepción: responden 402, no 403.

Restricciones de clave de API y token#

Restricciones de funciones del plan#

Restricciones de widget#

Otros dos mensajes 403 no tratan ni de claves ni de planes: Account suspended, que se devuelve en todas las solicitudes cuando la cuenta asociada a la clave o al token está suspendida, y robots.txt disallows fetching this URL (request sent respect_robots=true)., que devuelve perceive cuando pediste cumplimiento de robots y el destino no permite esa ruta.

404 Not Found#

409 Conflict#

410 Gone#

El artefacto existió, pero superó la ventana de retención de archivos de tu plan y ya no está en el almacenamiento. La retención es por plan; consulta Límites de tasa y cuotas.

Trata el 410 como definitivo para ese objeto. Volver a ejecutar la solicitud produce un artefacto nuevo; reintentar la descarga, no.

413 Payload Too Large#

Se devuelve cuando el archivo subido supera el tamaño máximo de archivo del plan.

{
    "detail": {
        "error": "File too large",
        "file_size": 10485760,
        "max_size": 5242880,
        "tier": "free",
        "key_type": "private"
    }
}

El límite se comprueba contra el número exacto de bytes de la parte subida, antes de que empiece cualquier trabajo de conversión. Un archivo cuyo tamaño sea exactamente max_size se acepta; solo se rechaza uno mayor. El encabezado Content-Length es un mecanismo de reserva para puntos de llamada antiguos que no entregan su objeto de subida a la comprobación.

POST /v2/ingest/files no usa esta forma. Responde 413 con un detail de cadena simple: File '{filename}' exceeds the {max_size}-byte limit.

Los techos por plan están en Límites de tasa y cuotas, y las rutas de subida a las que esto se aplica están en Ingesta de archivos.

Errores de conversión del navegador (415 / 422 / 502 / 504)#

Las conversiones de URL distinguen un fallo en el sitio de destino o en la entrada (un 4xx, 502 o 504 sobre el que puedes actuar) de un fallo en nuestro motor (un 500). Los tres endpoints V1 de conversión de URL (url-to-pdf, url-to-screenshot, url-to-markdown) devuelven estos fallos tipificados con un code legible por máquina junto a detail:

{
    "error": "Gateway Timeout",
    "code": "upstream_timeout",
    "detail": "The target site took too long to respond while rendering PDF for https://example.com."
}

Esos cinco son todo el vocabulario. Ninguna otra familia de endpoints emite un code, V2 incluido: un fallo de V2 vuelve como una cadena detail simple. La clase base del envoltorio define un sexto slug, conversion_error, pero nada lo lanza, así que nunca te llega. Ramifica sobre los cinco anteriores y trata cualquier otro valor como desconocido.

Un 504 también puede llegar en dos formas sin tipificar: {"error": "Request timeout"} cuando la solicitud supera el presupuesto de 300 segundos del gateway, y un detail de cadena simple con el mensaje de tiempo de espera cuando una conversión de documento (LibreOffice) se agota. Ninguna de las dos lleva un code.

422 Unprocessable Entity#

Los fallos de validación de esquema devuelven dos arrays paralelos. detail es la salida sin procesar del validador, que es lo que reasignas a los campos del formulario. errors es una cadena legible por personas por cada problema, que es lo que muestras al usuario.

{
    "detail": [
        {
            "loc": ["body", "max_pages"],
            "msg": "Input should be a valid integer, unable to parse string as an integer",
            "type": "int_parsing"
        }
    ],
    "errors": [
        "body.max_pages: Input should be a valid integer, unable to parse string as an integer (you sent 'ten')"
    ]
}

Vale la pena tratar tres valores de type por su nombre:

Un 422 con el código selector_not_found es otra cosa: una precondición de renderizado que falló, tratada en Errores de conversión del navegador.

429 Too Many Requests#

La limitación de tasa es un control de equidad de ventana corta e independiente de la cuota mensual de ops. Agotar la cuota responde 402; solo el limitador de tasa responde 429.

Un 429 incluye cuatro encabezados:

Estos encabezados aparecen solo en el 429. Las respuestas correctas no llevan encabezados de límite de tasa ni de ops restantes, así que no puedes leer tu presupuesto restante en una respuesta; revisa el uso en el panel. Consulta Límites de tasa y cuotas.

500 Internal Server Error#

Todo lo que falla fuera de un conversor nunca te llega como texto. Vuelve sin ningún detail:

{
    "error": "Internal server error",
    "event_id": "a1b2c3d4"
}

Un caso sorprende a mucha gente: un cuerpo JSON malformado enviado a un endpoint V1 de URL (url-to-pdf, url-to-screenshot, url-to-markdown, website-to-pdf, website-to-screenshot) devuelve este 500 en lugar de un 422, porque esos endpoints leen el cuerpo sin procesar. El mismo cuerpo malformado en un endpoint V2 devuelve un 422 con type: json_invalid.

Si encuentras errores 500 persistentes, es probable que el problema esté en el archivo o la URL de entrada. Prueba con una entrada diferente para aislar el problema.

503 Service Unavailable#

Existen dos compuertas de capacidad distintas y piden esperas diferentes, así que lee Retry-After en lugar de suponer una. Por lo demás, estos errores son transitorios: reintenta después de una breve espera.

Errores de los endpoints V2#

Los endpoints de inteligencia web V2 reutilizan los códigos de estado anteriores, con algunas condiciones específicas de V2 que vale la pena mencionar.

Cuota y plan (402 / 403)#

Las operaciones V2 se miden contra la misma cuota mensual unificada de ops que las conversiones V1: una op por unidad de trabajo. Cualquier plan de pago con excedente activado ($0.02/op) permite superar la asignación; si no, el tope es estricto.

Dos comportamientos de V2 deliberadamente no son errores. Agotar el saldo de créditos de IA no hace fallar la solicitud: la extracción de esquema recurre al resultado heurístico y CSS. Y una ejecución de distill con varias URLs que cruza el límite de ops a mitad de camino tampoco devuelve 402: se detiene ahí, devuelve las URLs que terminó, y añade una advertencia que indica cuántas se omitieron.

Validación (422)#

Todos los esquemas de solicitud V2 rechazan las claves desconocidas, así que un parámetro mal escrito es un 422 que nombra el campo. La forma del cuerpo se describe en 422 Unprocessable Entity.

Proveedor de búsqueda (502 / 503)#

El endpoint lookup depende de un proveedor de búsqueda externo (upstream). El texto de error sin procesar del proveedor nunca llega al cliente.

No encontrado (404)#

GET y DELETE sobre un operation_id, job_id o watcher_id de V2 que no existe, o que pertenece a otro proyecto, devuelven 404. La existencia nunca se filtra entre proyectos.

Aceptado (202)#

Ingest siempre es asíncrono: POST /v2/ingest responde 202 con un job_id que consultas mediante polling. Los lotes de perceive con más de 10 URLs responden 202 con estado queued. Un lote de 10 o menos normalmente responde en línea, pero si supera la ventana en línea degrada a 202 con estado processing y una advertencia, así que gestiona el 202 con cualquier tamaño de lote.

Un 202 también significa que los fallos posteriores no son errores HTTP. Consulta el trabajo y lee su carga de estado, tal como se describe en Trabajos síncronos y asíncronos.

Solución de problemas#

Problemas de autenticación#

• ¿Recibes un 401? Verifica que tu clave de API sea válida y esté activa en el panel. Si usas JWT, asegúrate de que el token no haya expirado (vida útil de 1 hora).
• ¿Recibes un 403 sobre uso desde el navegador? Estás usando una clave privada (sk_...) desde código del lado del cliente. Cambia a una clave pública con JWT para solicitudes desde el navegador.
• ¿Recibes un 403 sobre dominio? Agrega tu dominio a la lista de dominios permitidos de la clave de API en el panel.

Problemas de conversión#

• ¿Recibes un 400 sobre formato de archivo? Asegúrate de que la extensión del archivo subido coincida con el endpoint (por ejemplo, .json para json-to-xml, .docx para doc-to-pdf).
• ¿Recibes un 413? Tu archivo supera el límite de tamaño del plan. Lee detail.max_size de la respuesta, luego revisa el tamaño máximo de archivo de tu plan o actualízalo.
• ¿Recibes un 402? Alcanzaste tu cuota mensual de ops, el tope de watchers o el límite de almacenamiento, o el proyecto no tiene periodo de facturación activo. Revisa el uso en el panel y consulta Límites de tasa y cuotas.

Problemas de acceso a funciones#

• ¿Recibes un 403 sobre funciones del plan? La función V1 que intentas usar (async, lotes, webhooks, salida ZIP, autenticación básica) requiere un nivel de plan superior. Consulta la tabla de habilitación de funciones.
• ¿Recibes un 402 en un endpoint V2 que no tiene que ver con la cuota? Las restricciones de endpoints V2 responden 402, no 403. El mensaje dice ... is not available on your current plan. Upgrade to a V2-inclusive plan to access this endpoint.

Preguntas frecuentes#

¿Por qué la API devuelve 402 Payment Required en una conversión de archivo?#

Un 402 significa que se agotó un límite de uso: tu cuota mensual unificada de ops (500 ops en el plan Founding), el tope de watchers activos, o la asignación de almacenamiento de tu proyecto. También cubre dos casos ajenos a la cuota: un proyecto sin periodo de facturación activo, y un endpoint V2 desactivado en tu plan. Las solicitudes por lotes que superarían la cuota mensual de ops restante se rechazan de antemano con un 402 para todo el lote. Las conversiones V1 y las operaciones V2 consumen la misma cuota; cualquier plan de pago con excedente activado ($0.02/op) permite superarla. La limitación de tasa es un mecanismo distinto y responde 429.

¿Cómo soluciono un error 401 Unauthorized de la API de conversión?#

Verifica que la clave de API esté presente, comience con sk_ o pk_, y siga activa en el panel; las claves revocadas devuelven API Key revoked. Si te autenticas con un JWT, ten en cuenta que los tokens de acceso expiran después de 1 hora (Token has expired) y los tokens de actualización después de 7 días.

¿Por qué recibo 413 Payload Too Large al subir un archivo?#

El archivo subido supera el tamaño máximo de archivo de tu plan, medido a partir del número exacto de bytes de la parte subida antes de que empiece cualquier trabajo de conversión. Un archivo justo en el límite se acepta. El cuerpo del 413 anida un objeto estructurado bajo detail, con file_size, max_size (ambos en bytes), tier y key_type, así que léelo como detail.max_size y no como un campo de nivel superior.

¿Puedo usar una clave de API privada desde JavaScript en el navegador?#

No: una clave privada (sk_...) usada en una solicitud con un encabezado Origin de navegador devuelve 403 Private API keys cannot be used from browsers. Intercambia una clave pública por un JWT en /v1/auth/token y usa ese token para las llamadas a la API desde el navegador.

¿Es permanente un error 503 Service Unavailable de la API?#

No, los errores 503 como Converter not available: {endpoint} o Turnstile verification unavailable suelen ser transitorios. Reintenta la solicitud después de una breve espera.