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 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 HTTP: 404

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

template_not_found

Tipo: not_found_error · Código HTTP: 404

No se encontró ninguna plantilla con el ID proporcionado.

insufficient_credits

Tipo: insufficient_credits · Código HTTP: 402

No tiene suficientes créditos para realizar esta acción. Consulte GET /account para conocer sus available_credits actuales antes de reintentar.

rate_limit_exceeded

Tipo: rate_limit_error · Código HTTP: 429

Demasiadas solicitudes. Reduzca la velocidad y vuelva a intentarlo después de que se reinicie la ventana; consulte el encabezado de respuesta X-RateLimit-Reset y la guía de Límites de tasa.

internal_error

Tipo: internal_error · Código 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 si se pone en contacto con nosotros al respecto.

📮 contact email: [email protected]