# Manejo de Errores de la API — Tipos de Error, Códigos y doc_url

> Cada error de la v1 es un objeto JSON con type, code, message y doc_url. Esta página documenta la taxonomía completa de tipos de error y cada código de error individual, y es exactamente a lo que enlaza un doc_url devuelto.

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

```json
{
  "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`:

| Tipo | Significado |
| --- | --- |
| authentication_error | Algo está mal con cómo (o si) autenticó la solicitud. |
| invalid_request_error | La solicitud en sí está mal formada: falta un parámetro o es inválido. |
| not_found_error | El recurso al que hace referencia la URL (un documento, lote o ID de plantilla) no existe o no pertenece a su cuenta. |
| insufficient_credits | Su cuenta no tiene suficientes créditos para realizar la acción solicitada (de pago). |
| rate_limit_error | Ha superado la tasa de solicitudes para esta categoría de endpoint — consulte Límites de tasa . |
| internal_error | Algo 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](/developers/guides/idempotency) 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](/developers/guides/rate-limits).

### 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.

---

Source: https://imagetotable.ai/es/developers/guides/errors