Requêtes idempotentes

Une requête peut échouer alors que Sursa a déjà fait le travail : la connexion est coupée, ou votre processus redémarre avant l’arrivée de la réponse. Si vous renvoyez le même POST, vous risquez de créer une seconde fiche ou un second webhook. Une clé d’idempotence l’empêche.

Envoyez un en-tête Idempotency-Key avec chaque POST et PATCH. Si Sursa a déjà vu une requête avec cette clé, il n’exécute pas l’opération une seconde fois : il renvoie la réponse enregistrée la première fois.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

Une requête répétée reçoit le même statut et le même corps que la première, avec un en-tête supplémentaire :

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

La requête répétée a son propre X-Request-Id.

Choisir une clé

Utilisez une nouvelle valeur aléatoire, par exemple un UUID v4, pour chaque opération logique : « créer cette fiche », « enregistrer ce webhook ». Utilisez la même valeur pour chaque nouvelle tentative de cette opération, et jamais pour une autre.
Une bonne clé se déduit de vos propres données quand vous en avez, par exemple sync-2026-10-24-record-1042. Ainsi, même un job redémarré qui a perdu sa mémoire renvoie la même clé.
La clé compte de 1 à 255 caractères ASCII imprimables. Toute autre valeur renvoie 400 avec le code api.idempotency_key_invalid.

Ce que Sursa fait de la clé

Situation	Réponse
Première requête avec cette clé	L’opération s’exécute normalement.
Même clé, même requête, la première s’est terminée par `2xx` ou `4xx`	La réponse enregistrée, avec `Idempotency-Replayed: true`. L’opération ne s’exécute pas une seconde fois.
Même clé, la première requête est encore en cours	`409` `api.idempotency_in_progress` avec `Retry-After: 1`. Attendez, puis réessayez.
Même clé, mais méthode, chemin, `Content-Type` ou corps différent	`409` `api.idempotency_mismatch`. La clé est déjà prise par une autre requête.
La première requête s’est terminée par `5xx` ou `429`	La clé est libérée : la requête suivante avec cette clé exécute de nouveau l’opération.

Une clé est valable 24 heures. Passé ce délai, la même clé lance une nouvelle opération.
Les clés sont distinctes par organisation et par appelant : deux clés API différentes peuvent utiliser la même valeur sans interférer.
Une réponse d’erreur 4xx est elle aussi enregistrée. Une requête qui a échoué à la validation échoue de la même façon quand elle est répétée avec la même clé ; corrigez-la et envoyez-la avec une nouvelle clé.

Requêtes concernées

Méthode	Idempotency-Key
`POST`, `PATCH`	Envoyez-la. Chaque point de terminaison qui enregistre sa réponse pour une répétition mentionne l’en-tête dans la référence de l’API.
`GET`, `PUT`, `DELETE`	Inutile : par leur sens même, ces méthodes peuvent être répétées sans risque. L’en-tête est accepté et reste sans effet.
`POST` qui ne fait que lire, comme la recherche, les rapports financiers et `POST /v1/catalog/resolve`	Acceptée, mais rien n’est enregistré : la requête s’exécute simplement de nouveau.

Certaines opérations peuvent être répétées sans risque même sans l’en-tête :

PUT /v1/cards-by-external-id/{external_id} crée ou remplace la fiche qui porte votre identifiant ; une répétition avec le même contenu ne change rien.
Les documents d’une source personnalisée sont identifiés par votre external_id ; renvoyer le même document renvoie unchanged.
Une réponse en flux de POST /v1/chat utilise le champ request_id du corps au lieu de l’en-tête. Voir Créer un bot de questions-réponses.

Réessayer sans risque

Combinez la clé avec les règles de nouvelle tentative de la page Erreurs : créez la clé une seule fois, avant la première tentative, et envoyez-la avec chaque tentative de la même opération.