IN
INFYNIA

Idempotence

Réessayer un POST sans risque avec l'en-tête Idempotency-Key, et ce qui se passe quand une clé est réutilisée.

Pourquoi

Si une erreur réseau masque la réponse d'un POST, vous ne savez pas si l'appel a été lancé. Le renvoyer à l'aveugle pourrait appeler quelqu'un deux fois. Avec une clé d'idempotence, le nouvel essai renvoie la première réponse au lieu de refaire le travail.

Comment

  • Envoyez un en-tête Idempotency-Key (1 à 255 caractères) sur tout POST. Choisissez une valeur liée à votre événement métier, comme un identifiant de commande, ou un UUID aléatoire conservé avec l'opération.
  • Pendant 24 heures, une requête avec la même clé, la même route et le même corps renvoie le statut et le corps de la première, avec l'en-tête Idempotent-Replayed: true.
  • La même clé avec un autre corps ou une autre route répond 422 avec idempotency_mismatch.
  • Seules les réponses réussies (2xx) sont conservées. Une erreur (4xx, 5xx, 429) n'est jamais conservée et libère la clé : corrigez la cause (agent inactif, appel hors horaires...) puis réessayez avec la même clé, la requête s'exécute réellement.
  • Une clé hors de 1 à 255 caractères répond 400 avec invalid_idempotency_key.
# Same key, same body: the first response is replayed (Idempotent-Replayed: true)
curl -i -X POST https://infynia.quantylcore.com/api/v1/calls \
  -H "Authorization: Bearer $INFYNIA_API_KEY" \
  -H "Idempotency-Key: order-1042-callback" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "AGENT_ID", "to": "+15555550100"}'

Deux requêtes avec la même clé envoyées en même temps sont sérialisées : la seconde reçoit 409 avec idempotency_in_progress tant que la première s'exécute. Attendez, puis renvoyez : vous obtenez la réponse conservée. La clé est propre à la clé d'API et à son mode : la même valeur utilisée avec une autre clé, ou avec une clé de test puis une clé live, ne partage jamais de réponse.

Le champ idempotencyKey de POST /v1/calls

Le corps de POST /v1/calls accepte aussi un champ idempotencyKey. C'est un mécanisme distinct, qui déduplique les appels dans la durée : quand un appel avec la même valeur existe déjà, la réponse est 200 avec duplicate: true. Utilisez l'en-tête pour les nouveaux essais sûrs et le champ du corps si vous voulez que l'appel lui-même soit unique.