En-tête Idempotency-Key

L’API Bird permet la déduplication facultative des requêtes via l’en-tête Idempotency-Key. Cette page définit le contrat HTTP ; pour la stratégie de nouvelle tentative, consultez Idempotence.

Les mutations limitées à un espace de travail ou à une organisation prennent en charge la restitution des réponses décrite ci-dessous. Les opérations limitées à un utilisateur, les opérations non authentifiées sans portée définie et les flux ne l’utilisent pas. Les opérations dotées d’un contrat de restitution distinct définissent leur comportement sur leur page de référence.

Si vous omettez l’en-tête ou envoyez une valeur vide, la requête est traitée normalement, sans déduplication. Pour les endpoints qui déclarent cet en-tête, une clé de plus de 255 caractères renvoie 422 avec le code E01001 ValidationError.

Les clés sont limitées à votre espace de travail, ou à votre organisation pour les endpoints au niveau de l’organisation, et conservées pendant environ 3 heures. Après cette période, une requête qui réutilise la clé est traitée comme une nouvelle requête.

Une réponse rejouée est identique octet pour octet à l'originale (même code de statut, même corps), distinguée uniquement par l'en-tête supplémentaire :

HTTP/1.1 202 Accepted
Idempotency-Replay: true

"Identical request" couvre la méthode, l’endpoint, les paramètres de chemin et de requête, ainsi que le corps brut de la requête. Toute différence dans ces valeurs, y compris les espaces dans JSON, déclenche E01005. Les envois multipart comparent les noms des parties, les noms de fichiers et leur contenu ; les délimiteurs et l’ordre des parties n’affectent pas la restitution. Les deux erreurs 409 sont renvoyées dans la réponse d’erreur standard.

Les réponses conservées peuvent inclure des rejets 4xx. Utilisez une nouvelle clé lorsque vous corrigez une requête : si son rejet a été conservé, une nouvelle tentative inchangée le restitue, et une requête modifiée renvoie 409 E01005 IdempotencyKeyReuse.

Les réponses 5xx ne sont jamais mises en cache. Réessayez avec un délai exponentiel en utilisant la même clé et la même requête. E01033 IdempotencyUnavailable signifie que cette tentative ne s'est pas exécutée ; cela ne décrit pas le résultat d'une tentative précédente. Conservez la clé à chaque réessai.

Une opération peut prendre effet avant que sa réponse ne soit conservée. Si cette réponse est perdue, ou si le verrou en cours expire, un réessai peut exécuter l'opération à nouveau. Un délai d'attente dépassé ou une autre réponse 5xx ne prouve donc pas que l'opération n'a eu aucun effet.

Les SDK officiels attachent un UUID Idempotency-Key généré automatiquement à chaque requête de mutation, créé une seule fois par appel logique et réutilisé pour toutes les tentatives de réessai de cet appel. Vous pouvez fournir votre propre clé par appel (idempotencyKey en TypeScript, option.WithIdempotencyKey en Go, idempotency_key en Python) lorsqu'une opération logique couvre plusieurs appels SDK. Pour détecter un rejeu, lisez l'en-tête de réponse Idempotency-Replay via l'accesseur de métadonnées de transport de chaque SDK : .withResponse() en TypeScript, option.WithResponseInto en Go et with_raw_response en Python.