Idempotence

Envoyez un en-tête Idempotency-Key avec chaque POST, PATCH ou DELETE, et une requête réessayée rejoue la réponse d'origine au lieu de s'exécuter deux fois.

Les réseaux tombent en panne entre « la requête a été envoyée » et « la réponse est arrivée ». Sans protection, une nouvelle tentative après une telle panne crée un second produit, met en file d’attente une seconde tâche facturable ou soumet un second import. L’en-tête HTTP Idempotency-Key supprime ce risque.

curl https://api.veeton.com/v1/tasks/beautifier \
  -H "Authorization: Bearer $VEETON_KEY" \
  -H "Idempotency-Key: 4d1b9f6e-6c2a-4c1e-9c3f-2a7e8b0d1f22" \
  -H "Content-Type: application/json" \
  -d @task.json

N’importe quelle chaîne opaque de 255 caractères au maximum convient ; un UUID par opération logique est le choix habituel. Les clés sont limitées au périmètre de votre organisation et expirent au bout de 24 heures.

Ce que fait une clé

Situation	Résultat
Même clé, même requête	La réponse stockée est rejouée telle quelle, avec `Idempotent-Replayed: true`.
Même clé, mais méthode, chemin ou corps différent	`422 idempotency_key_reused`. Utilisez une nouvelle clé pour chaque opération.
Même clé alors que la première requête est encore en cours	`409 request_in_progress`. Réessayez une fois qu’elle est terminée.
Pas de clé	La requête s’exécute normalement. L’en-tête est facultatif.

Les requêtes GET sont idempotentes par nature et ne sont jamais suivies.

Réessayer après une erreur

Un 4xx est un résultat à part entière et est rejoué comme n’importe quel autre : une requête rejetée est déterministe et la rejouer ne vous coûte rien.

L’exception est 402 payment_required. Il dépend de votre solde, pas de la requête, et n’est donc pas stocké : une fois des crédits ajoutés, une nouvelle tentative avec la même clé crée la tâche.

Un 5xx n’est pas stocké. La clé est libérée, de sorte qu’une nouvelle tentative avec la même clé réexécute réellement la requête au lieu de rejouer l’échec. Le revers : si l’opération avait déjà pris effet avant l’erreur, une nouvelle tentative peut en produire une seconde. C’est le même compromis que fait Stripe, et c’en est la meilleure moitié ; l’alternative serait une opération que vous ne pourriez jamais mener à terme.

Si une requête cesse totalement de répondre (un crash de notre côté avant que quoi que ce soit n’ait été enregistré), la clé se libère d’elle-même quelques minutes plus tard. Une nouvelle tentative ultérieure n’est jamais bloquée définitivement.