Sign inGet Started
Commencer
Guides
Référence API
SDK
CLI
Base de connaissances
Changelog

En-tête Idempotency-Key

Utilisez Idempotency-Key pour réessayer une requête sans créer d'opération en double. La garantie est une acceptation unique : pendant la période de rétention de 3 heures, les nouvelles tentatives avec la même clé et une requête identique doivent aboutir à l'opération d'origine, même si vous en avez perdu la réponse. Pour la stratégie de nouvelle tentative, consultez Idempotence.

En-tête de requête

En-têteContraintes
Idempotency-KeyFacultatif. Toute chaîne non vide de 255 caractères au maximum ; un UUID v4 est recommandé. Pris en compte pour les opérations POST, PATCH, PUT et DELETE compatibles ; ignoré pour GET, HEAD et OPTIONS.

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.

Sémantique de la réponse

ScénarioRéponse
Première requête avec une cléTraitée normalement ; une réponse terminée peut être conservée pour être restituée ; les réponses 5xx ne sont pas conservées.
Même clé, requête identique pendant la rétentionL'opération d'origine ; une réponse conservée est restituée avec Idempotency-Replay: true.
Même clé, requête différente409 avec E01005 IdempotencyKeyReuse. Générez une nouvelle clé pour la nouvelle requête.
Même clé, requête d'origine encore en cours409 avec E01004 RequestInProgress. Attendez, puis réessayez avec la même clé et une requête identique.
La requête d'origine a renvoyé 5xxLa réponse en erreur n'est pas conservée. Réessayez avec la même clé et une requête identique.
Protection d'idempotence indisponible avant l'exécution503 avec E01033 IdempotencyUnavailable. Cette tentative n'est pas exécutée ; réessayez avec la même clé et la même 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 :

Exemple de code
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.

En cas de délai dépassé ou de 5xx, réessayez avec un délai d'attente progressif et borné, en utilisant la même clé et une requête identique dans un délai de trois heures. La garantie d'acceptation unique s'applique même si la réponse d'origine a été perdue. 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 nouvelle tentative.

Pour un envoi de message, l'acceptation unique signifie qu'un seul envoi est accepté pour l'ensemble des nouvelles tentatives correspondantes. Vérifiez le statut du message pour confirmer la remise. Après trois heures, vérifiez le résultat de l'opération d'origine avant de soumettre à nouveau la requête : une clé expirée ou une nouvelle clé peut créer une autre opération.

Comportement des SDK

Les SDK officiels attachent un UUID Idempotency-Key généré automatiquement à chaque requête de mutation. Il est créé une seule fois par appel logique et réutilisé pour toutes les nouvelles tentatives de cet appel. Vous pouvez fournir votre propre clé par appel (idempotencyKey en TypeScript, option.WithIdempotencyKey en Go, idempotency_key en Python, new RequestOptions(idempotencyKey: ...) en PHP) 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.

Ressources associées

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Obtenir un guide d'implémentation