Guía

Manejo de Errores

Toda solicitud v1 fallida — toda respuesta no 2xx — devuelve la misma estructura JSON, detallada a continuación. Esta página es también a lo que enlaza el doc_url de cada error: cada código tiene su propia sección anclada, por lo que seguir un doc_url desde una respuesta de error real lo lleva directamente a la explicación de ese código exacto.

La estructura del error

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "A required parameter is missing.",
    "doc_url": "https://imagetotable.ai/developers/guides/errors#missing_parameter",
    "param": "file"
  }
}
  • type — la categoría general de este error (consulte la tabla a continuación). Útil para una ramificación general en su código de manejo de errores ("¿es un problema de autenticación o de validación?") sin verificar cada code individual.
  • code — el identificador de error específico y estable. Esto es lo que debe comparar en el código — no cambiará incluso si la redacción de message se mejora más adelante.
  • message — una explicación legible para humanos. Útil para registros y depuración, no está pensada para ser analizada.
  • doc_url — un enlace directo a la sección de esta página para ese code exacto.
  • param — presente solo en errores de tipo validación (missing_parameter, invalid_parameter, duplicate_field_name), indicando el campo de solicitud específico que causó el error. Se omite por completo — no es null — cuando no corresponde.

Tipos de error

Cada code pertenece exactamente a un type:

TipoSignificado
authentication_errorAlgo está mal con cómo (o si) autenticó la solicitud.
invalid_request_errorLa solicitud en sí está mal formada: falta un parámetro o es inválido.
not_found_errorEl recurso al que hace referencia la URL (un documento, lote o ID de plantilla) no existe o no pertenece a su cuenta.
insufficient_creditsSu cuenta no tiene suficientes créditos para realizar la acción solicitada (de pago).
rate_limit_errorHa superado la tasa de solicitudes para esta categoría de endpoint — consulte Límites de tasa.
internal_errorAlgo salió mal en nuestro lado, no en el suyo.

Un caso especial: processing_error

processing_error no es un type que verá nunca en una respuesta de nivel superior {"error": ...}. Nunca provoca que una llamada a la API falle por sí sola. En cambio, describe un documento individual dentro de un lote que no pudo extraerse; lo verá reflejado como "status": "failed" en ese documento dentro de una respuesta GET /batches/{batch_name}/results que por lo demás es 200 OK, junto a documentos del mismo lote que se procesaron correctamente. No trate un fallo a nivel de documento dentro de una llamada API exitosa como un error para reintentar todo el lote; revise el status de cada documento.

Códigos de error

missing_api_key

Tipo: authentication_error · Código HTTP: 401

No se proporcionó ninguna clave de API. Envíela como Authorization: Bearer <key>.

invalid_api_key

Tipo: authentication_error · Código HTTP: 401

La clave de API proporcionada no es válida o la cuenta a la que pertenece está deshabilitada.

plan_required

Tipo: authentication_error · Código HTTP: 403

La API no está disponible en el plan Free. Actualice a Basic o superior para usarla.

missing_parameter

Tipo: invalid_request_error · Código HTTP: 400

Falta un parámetro obligatorio. Consulte param en el objeto de error para saber cuál es.

invalid_parameter

Tipo: invalid_request_error · Código HTTP: 400

Un parámetro tiene un valor no válido. Consulte param y message para más detalles: este es un código genérico que cubre desde una cadena crop mal formada hasta un limit fuera de rango o un lote sin elementos procesables.

duplicate_field_name

Tipo: invalid_request_error · Código HTTP: 400

Ya existe un campo con este nombre en esta plantilla. Los nombres de campo deben ser únicos dentro de una plantilla.

idempotency_key_reused

Tipo: invalid_request_error · Código HTTP: 400

Esta Idempotency-Key ya se usó para una solicitud con parámetros diferentes. Use una clave nueva para una solicitud genuinamente distinta; consulte Idempotencia para conocer el comportamiento completo.

document_not_found

Tipo: not_found_error · Código de estado HTTP: 404

No se encontró ningún documento con el ID proporcionado (o no existe, o no pertenece a su cuenta).

batch_not_found

Tipo: not_found_error · Código de estado HTTP: 404

No se encontró ningún lote con el nombre proporcionado.

template_not_found

Tipo: not_found_error · Código de estado HTTP: 404

No se encontró ninguna plantilla con el ID proporcionado.

insufficient_credits

Tipo: insufficient_credits · Código de estado HTTP: 402

No tiene suficientes créditos para realizar esta acción. Consulte GET /account para ver sus available_credits actuales antes de volver a intentarlo. Si esto ocurre en un lote que normalmente está dentro del presupuesto, compruebe si a la cuenta se le ha asignado un nivel de modelo no estándar (Advanced/Premium cuestan 3x/6x la tarifa estándar por documento) — consulte la guía de Configuración de la cuenta y comportamiento de la API.

rate_limit_exceeded

Tipo: rate_limit_error · Código de estado HTTP: 429

Demasiadas solicitudes. Reduzca la velocidad y vuelva a intentarlo después de que se restablezca la ventana — consulte la cabecera de respuesta X-RateLimit-Reset y la guía de Límites de velocidad.

internal_error

Tipo: internal_error · Código de estado HTTP: 500

Se produjo un error inesperado. Si persiste, el problema es nuestro, no suyo — si puede reproducirlo de forma fiable, esa información es útil para incluirla si se pone en contacto con nosotros al respecto.

📮 contact email: [email protected]