Guía

Idempotencia

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:

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:

{
  "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.

📮 contact email: [email protected]