Guide

Idempotence

Les appels réseau échouent et expirent. Lorsque cela arrive à une requête qui consomme des crédits ou crée une ressource, la réessayer naïvement peut dépenser ces crédits deux fois. L'en-tête Idempotency-Key résout ce problème : envoyez la même clé lors d'une nouvelle tentative, et vous obtenez exactement la même réponse que l'appel d'origine — sans que l'opération ne soit exécutée à nouveau.

Fonctionnement

Ajoutez un en-tête Idempotency-Key avec une chaîne unique générée par le client (un UUID est un bon choix) à une requête qui le prend en charge :

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 clé est stockée par (votre compte, valeur de la clé, point de terminaison) pendant 24 heures. Si la même requête (même point de terminaison, même clé) arrive à nouveau dans cette fenêtre, la réponse d'origine — même code de statut, même corps — est rejouée, et l'opération elle-même ne s'exécute pas une seconde fois. Cela signifie qu'un appel process relancé avec la même clé ne déduit pas deux fois les crédits, et qu'un téléversement documents relancé avec la même clé ne crée pas un second document.

Les requêtes sans en-tête Idempotency-Key se comportent exactement comme avant — rien n'est stocké, rien n'est rejoué. L'en-tête est entièrement facultatif.

Quels endpoints le prennent en charge

Seuls les endpoints qui consomment des crédits ou créent une ressource acceptent Idempotency-Key — cela ne présente aucun intérêt sur un GET en lecture seule, puisque répéter une lecture est toujours sûr en soi :

  • POST /documents (création de document)
  • POST /batches/{batch_name}/process (démarre le traitement, déduit des crédits)
  • POST /documents/{document_id}/bbox (déclenche l'étape payante d'annotation bbox)

Réutiliser une clé avec des paramètres différents

Un Idempotency-Key est conçu pour réessayer la même requête exacte, pas comme un libellé générique. Si vous réutilisez une clé déjà utilisée, mais cette fois avec des paramètres de requête différents — un batch_name différent, un corps de requête différent — l'API ne rejoue pas silencieusement l'ancienne réponse (ce qui serait erroné pour une requête différente) et ne devine pas laquelle vous vouliez. Elle renvoie une erreur 400 idempotency_key_reused à la place. Générez une nouvelle clé dès que la requête est réellement différente, même si elle cible le même type d'opération.

Exemple : une réponse rejouée

Le deuxième appel ci-dessous, effectué avec la même clé qu'un appel déjà réussi, renvoie le même corps et le même code de statut que le premier — il ne déduit pas à nouveau les crédits :

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

Ce qui est enregistré

Seules les réponses réussies (2xx) sont sauvegardées pour rejeu. Si l'appel d'origine a échoué — une erreur de validation, des crédits insuffisants, quoi que ce soit de non-2xx — rien n'est enregistré, et réessayer avec la même clé tente simplement l'opération à nouveau. C'est délibéré : une erreur est exactement la situation où vous voulez que votre nouvelle tentative essaie réellement à nouveau, pas qu'elle rejoue le même échec jusqu'à l'expiration de la clé 24 heures plus tard.

📮 contact email: [email protected]