Idempotence
Utiliser des idempotency keys stables pour éviter que les retries créent des usages, livraisons ou actions en double.
L’idempotence évite les effets de bord en doublon lorsqu’une requête est retryée.
Utilisez des idempotency keys pour les écritures retryables comme les événements d’ingestion directe, les imports batch, les tests webhook, les opérations de replay et les appels de workflow qui peuvent être retryés en sécurité.
Pourquoi c’est important
Les réseaux échouent, les workers retryent et les providers peuvent expirer.
Sans idempotence, un retry peut créer des événements d’usage en doublon, des coûts en doublon ou des effets downstream en doublon.
Avec l’idempotence, Kadryn peut reconnaître que deux requêtes représentent la même opération logique.
Header
Idempotency-Key: usage-event-prod-api-2026-07-06-001
Utilisez la même clé pour les retries de la même opération logique.
Utilisez une clé différente pour une opération logique différente.
Bonnes clés
De bonnes idempotency keys sont :
- stable;
- unique par opération logique;
- déterministes lors des retries;
- assez ciblées pour éviter les collisions;
- sûres à logger.
Exemples :
usage-event-prod-api-openai-req-abc123
invoice-run-2026-07-06-001:step-01
batch-import-2026-07-06:page-004
webhook-test-endpoint-123:2026-07-06T12:00
Mauvaises clés
Évitez :
random-value-created-on-every-retry
timestamp-only
user-input-only
same-key-for-all-events
full-secret-or-token
Une clé aléatoire par retry annule l’idempotence.
Exemple d’ingestion directe
curl "$KADRYN_API_BASE_URL/usage/events" \
-H "Authorization: Bearer $KADRYN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: usage-event-openai-req-abc123" \
-d '{
"timestamp": "2026-07-06T12:00:00.000Z",
"provider": "openai",
"model": "gpt-4.1-mini",
"inputTokens": 1200,
"outputTokens": 300,
"costCents": "4",
"project": "prod-api",
"environment": "prod"
}'
Exemple de retry Gateway
curl "$KADRYN_GATEWAY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $KADRYN_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Kadryn-Request-Group-Id: invoice-run-2026-07-06-001" \
-H "Idempotency-Key: invoice-run-2026-07-06-001:step-01" \
-d '{
"model": "gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "Summarize invoice status."
}
]
}'
Règles de retry
Lors d’un retry :
- conservez la même idempotency key;
- conservez le même request group ID;
- préservez le contexte de trace;
- utilisez un backoff exponentiel;
- arrêtez après un nombre borné de tentatives;
- ne retryez pas les erreurs permanentes.
Retryable vs permanent erreurs
Retryez généralement :
- rate limits;
- network timeouts;
- temporary server erreurs;
- transient provider erreurs.
Ne retryez pas aveuglément :
- authentication erreurs;
- validation erreurs;
- policy blocks;
- manquant provider clés;
- permission erreurs.
Dépannage
Je vois encore des doublons
Vérifiez si les retries réutilisent la même idempotency key et si l’événement source possède un provider request ID ou une clé d’ingestion stable.
Un retry retourne le résultat original
C’est attendu. Kadryn peut retourner le résultat existant pour la même opération logique.
Une collision de clé s’est produite
Rendez la clé plus spécifique. Incluez le provider request ID, l’étape de workflow, le bucket temporel ou la page de batch.