# Idempotencia — Reintentar de forma segura con la cabecera Idempotency-Key

> Use la cabecera Idempotency-Key para reintentar de forma segura las cargas de documentos, el procesamiento por lotes y los disparadores de bbox sin pagar ni ejecutar la misma operación dos veces.

Las llamadas de red fallan y expiran. Cuando eso ocurre en una solicitud que gasta créditos o crea un recurso, reintentarla ingenuamente puede gastar esos créditos dos veces. La cabecera `Idempotency-Key` soluciona esto: envíe la misma clave en un reintento y obtendrá exactamente la misma respuesta que la llamada original, sin que se ejecute de nuevo.

## Cómo funciona

Añada una cabecera `Idempotency-Key` con cualquier cadena única generada por el cliente (un UUID es una buena opción) a una solicitud que lo soporte:

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3e9a2c-9b41-4e6a-8c3d-2f1a5b6c7d8e" \
  -d '{"fields": [{"name": "invoice_number"}, {"name": "total_amount"}]}'
```

La clave se almacena por `(su cuenta, valor de clave, endpoint)` durante **24 horas**. Si la misma solicitud exacta (mismo endpoint, misma clave) llega de nuevo dentro de esa ventana, se reproduce la respuesta original —mismo código de estado, mismo cuerpo— y la operación no se ejecuta una segunda vez. Esto significa que una llamada `process` reintentada con la misma clave no descuenta créditos dos veces, y una carga de `documents` reintentada con la misma clave no crea un segundo documento.

Las solicitudes sin una cabecera `Idempotency-Key` se comportan exactamente como antes —no se almacena nada, no se reproduce nada. La cabecera es completamente opcional.

## Qué endpoints lo admiten

Solo los endpoints que consumen créditos o crean un recurso aceptan `Idempotency-Key`; no tiene utilidad en una operación de solo lectura `GET`, ya que repetir una lectura siempre es seguro por sí mismo:

- `POST /documents` (creación de documentos)
- `POST /batches/{batch_name}/process` (inicia el procesamiento, descuenta créditos)
- `POST /documents/{document_id}/bbox` (activa el paso pago de anotación de bbox)

## Reutilizar una clave con parámetros diferentes

Un `Idempotency-Key` está diseñado para reintentar la *misma* solicitud exacta, no como una etiqueta de uso general. Si reutiliza una clave que ya ha usado, pero esta vez con parámetros de solicitud diferentes — un `batch_name` distinto, un cuerpo de solicitud diferente — la API no reproduce silenciosamente la respuesta anterior (lo cual sería incorrecto para una solicitud diferente) ni adivina cuál de ellas pretendía. En su lugar, devuelve un error 400 `idempotency_key_reused`. Genere una clave nueva siempre que la solicitud sea genuinamente diferente, incluso si apunta al mismo tipo de operación.

## Ejemplo: una respuesta reproducida

La segunda llamada a continuación, realizada con la misma clave que una llamada que ya tuvo éxito, devuelve el mismo cuerpo y código de estado que la primera — no descuenta créditos nuevamente:

```json
{
  "batch_name": "260716-4K9P",
  "queued": 2,
  "quality": "fast",
  "webhook_registered": false
}
```

## Qué se registra

Solo las respuestas exitosas (2xx) se guardan para reproducción. Si la llamada original falló — un error de validación, créditos insuficientes, cualquier cosa que no sea 2xx — no se registra nada, y reintentar con la misma clave simplemente intenta la operación desde cero. Esto es deliberado: un error es exactamente la situación en la que desea que su reintento realmente lo intente de nuevo, no que reciba la misma falla reproducida hasta que la clave expire 24 horas después.

---

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