Idempotence

Un client qui n’a pas vu la réponse (une coupure réseau, un délai dépassé, le rejeu automatique d’une bibliothèque HTTP) rejoue sa requête. Sans mémoire, POST /api/v1/workflows créerait deux workflows et POST /api/v1/messages/send enverrait deux mails. Avec une Idempotency-Key, le rejeu rend la réponse d’origine, à l’identique, et rien n’arrive deux fois.

Les routes qui l’acceptent

Tous les POST qui créent ou déclenchent quelque chose : créer un workflow, le dupliquer, le publier, le faire tourner (test, run), rejouer ou annuler des exécutions, émettre un signal, envoyer un message ou y répondre, importer des contacts ou des lignes, installer un template, créer une table, une colonne ou des lignes, décider une approbation, envoyer depuis la revue, lancer une analyse ou une conversation avec l’assistant.

Dans la référence, ces routes portent la mention « Cette opération accepte un en-tête Idempotency-Key » ; dans le document OpenAPI, l’extension x-idempotency-key: true et un paramètre d’en-tête Idempotency-Key. Une clé envoyée à toute autre route est ignorée.

Comment s’en servir

Produisez une clé par intention (un UUID convient parfaitement), envoyez-la avec la requête, et renvoyez la même si vous devez réessayer :

POST /api/v1/workflows HTTP/1.1
Authorization: Bearer mk_…
Content-Type: application/json
Idempotency-Key: 6f1d4c2e-6b3a-4a0e-9d2b-7c5e1f0a8b43

{ "name": "Triage des factures" }

• La clé fait de 1 à 200 caractères, à votre choix. Une clé vide ou plus longue est un 400 idempotency.invalid_key.
• La mémoire est par appelant et par route : la même clé sur POST /api/v1/workflows et sur POST /api/v1/tables sont deux mémoires différentes, et deux clés d’API (ou deux membres) n’en partagent jamais une. L’appelant est la clé d’API quand il y en a une, le membre sinon.
• La mémoire dure 24 heures. Au-delà, la même clé démarre une requête neuve.

Les trois issues

Situation	Ce qui se passe
Première fois	La clé est réservée, la route s’exécute, le statut et le corps de sa réponse sont rangés. La réponse est la réponse normale.
Rejeu, même clé, même requête	La réponse rangée est rendue, même statut et même corps, sans repasser par la route. Elle porte l’en-tête Idempotency-Replayed: true.
Réutilisation, même clé, autre requête	422 idempotency.key_reused. Rendre la réponse d’une autre requête serait pire que de dupliquer.

« Même requête » signifie la même URL et le même corps JSON, comparés octet par octet après sérialisation. Réordonner les clés du corps ou changer une valeur en fait une autre requête.

Deux cas de plus :

• Un rejeu qui arrive pendant que la première requête court encore reçoit 409 idempotency.in_progress avec Retry-After: 1. Attendez et rejouez.
• Une réponse de statut 5xx libère la clé : après une panne du serveur, vous devez pouvoir réessayer, et ce nouvel essai exécute la route pour de vrai.

Ce qui n’est pas mémorisé

La réponse rangée est plafonnée à 64 Ko. Au-delà, la requête s’exécute normalement mais n’est pas mémorisée, et la réponse le dit par Idempotency-Replayed: unsupported. Un rejeu exécuterait alors la route une seconde fois. En pratique, toutes les routes qui créent répondent bien en dessous de cette limite ; le plafond existe par sécurité.

Une requête sans Idempotency-Key n’est jamais mémorisée ni dédoublonnée : la rejouer fait ce qu’elle dit, deux fois.

Les routes idempotentes par nature

Certaines routes n’ont pas besoin de l’en-tête parce que les appeler deux fois a le même effet qu’une : POST /api/v1/workflows/{id}/resume sur un workflow qui n’est pas en pause rend 200, POST /api/v1/api-keys/{id}/revoke garde la première date de révocation, POST /api/v1/executions/incidents/{id}/acknowledge garde le premier instant. Les routes PUT remplacent un état et se rejouent aussi ; PUT /api/v1/workflows/{id}/draft propose expectedDraft pour le contrôle de concurrence (voir Workflows).