Idempotence

Le réseau tombe en panne. Si un POST expire, vous ne savez pas s'il a été appliqué, et le relancer à l'aveugle pourrait créer un produit en double. L'en-tête Idempotency-Key résout ce problème :

curl -X POST https://api.nembol.com/rest/v1/products \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: 7d5c1f6e-2f5b-4a1e-9c3d-0a8b7c6d5e4f" \
  -d '{ "title": "…" }'

• Générez une clé unique par opération logique (un UUID est parfait), et réutilisez la même clé quand vous relancez cette opération.
• Rejouer la même clé avec le même contenu renvoie la réponse originale enregistrée (code de statut et corps identiques, plus l'en-tête Idempotent-Replayed: true). Rien n'est réexécuté. Les erreurs sont aussi enregistrées : une 4xx (par ex. une 422) est rejouée telle quelle, même si la cause a été corrigée depuis, de votre côté ou du nôtre. Envoyez donc une nouvelle clé après avoir modifié la requête ou après une correction. Une 5xx n'est jamais enregistrée : relancer avec la même clé exécute de nouveau la requête.
• Rejouer la même clé avec un contenu différent échoue avec 409 (idempotency_key_reused). Les clés ne sont jamais réutilisées silencieusement.
• Les clés sont conservées 24 heures ; longueur maximale de 255 caractères.

Prise en charge (et recommandée) sur chaque endpoint POST, PATCH et DELETE.

Recette de relance : en cas d'expiration ou de 5xx, relancez avec la même clé et un délai exponentiel (par ex. 1 s, 2 s, 4 s, …) ; en cas de 429, attendez Retry-After, puis relancez avec la même clé.

Dernière mise à jour le 20 octobre 2026