Idempotency

Tous les endpoints de l’API AstroWay sont naturellement idempotents : le même input donne toujours le même output, sans effets secondaires (sauf débit de crédits et journalisation de l’utilisation).

Cela signifie que les tentatives de retry en cas d’erreurs réseau sont sûres. Mais pour que la requête de retry ne débite pas les crédits deux fois, il faut transmettre l’en-tête Idempotency-Key.

Comment utiliser

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key - une chaîne arbitraire de jusqu’à 64 caractères, unique pour chaque opération logique. Recommandé : ULID ou UUID v4.

Garanties

• Pendant les 24 heures suivant la première requête avec cette clé, les requêtes répétées avec la même clé retournent la même réponse sans recalcul et sans débit de crédits.
• Si le corps de la requête diffère de l’original : une réponse 409 Conflict avec le code idempotency_key_reuse est retournée.
• Après 24 heures, la clé est oubliée, une nouvelle requête avec la même clé sera traitée normalement.

Note

L’idempotence est une protection contre le double débit en cas de pannes réseau, pas un cache. Pour le caching, utilise le mécanisme naturel X-Cache (5 minutes, voir Crédits et limites).

Quand l’utiliser

• Dans les handlers de webhooks, où les tentatives de retry proviennent d’un système externe (par exemple, un fournisseur de paiement ou une CRM envoie un événement que tu parses et pour lequel tu effectues un calcul)
• Dans les jobs en arrière-plan, où le retry est le comportement standard en cas d’échec
• Dans les pipelines CI/CD, où un test peut être relancé

Pour les interactions normales ” l’utilisateur clique sur un bouton → on affiche la carte ”, l’idempotence n’est pas nécessaire - l’utilisateur verra le résultat de toute façon, et il n’y a généralement pas de clics répétés.

Quand ne pas l’utiliser

• N’ajoute pas de clé pour économiser des crédits sur des requêtes identiques : pour cela, il y a X-Cache (gratuit, 5 minutes)
• Ne génère pas de clé à partir du hash(body) : tu perdras alors le comportement par défaut de l’Idempotency-Key (réponse 409 répétée en cas de différence dans le corps de la requête)