Clé d’idempotence
Envoyez une clé d’idempotence avec les requêtes de l’API System One pour relancer une décision sans double débit de crédits.
Nouvelle opération logique → un nouveau UUID aléatoire. Reprise ou récupération de la même opération → la même clé conservée et la requête complète. Relancer volontairement la même entrée est une nouvelle opération, pas une reprise. Une clé d’opération permet à un client HTTP ou SDK de récupérer un résultat réussi après une réponse perdue, sans nouvelle évaluation ni nouveau débit, pendant la fenêtre de rétention.
Prêt pour les questions
Q : Qu’est-ce qu’une clé d’idempotence dans l’API System One ? A : Un jeton généré côté client. Les relances renvoient le même résultat de décision sans double débit de crédits.
Prêt pour les questions
Qu’est-ce qu’une clé d’idempotence dans l’API System One ? Un jeton généré côté client. Les relances renvoient le même résultat de décision sans double débit de crédits.
Quand l’envoyer ? Dès que le client peut réessayer la même décision logique après un délai dépassé, une erreur réseau ou une erreur 5xx.
Pourquoi une clé d’idempotence
Une relance après un délai dépassé ou une erreur 5xx ne doit pas créer un second débit. La clé d’idempotence relie une relance à l’opération d’origine : le service compare la requête canonique validée et renvoie la réponse enregistrée au lieu d’évaluer à nouveau.
La portée est le compte : la clé est scoped au compte, y compris à travers toutes ses clés d’API, et n’est jamais transmise en amont. Sans clé d’opération, répéter une requête est une évaluation distincte et facturable.
Comment l’envoyer
Envoyez l’en-tête de requête Idempotency-Key pour chaque opération. Créez son UUID une fois, avant le premier envoi, et conservez-le avec la requête complète.
Les caractères autorisés sont ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$ : 1 à 128 caractères, commençant par une lettre ou un chiffre. Une valeur invalide renvoie HTTP 422 invalid_idempotency_key.
curl --include 'https://system-one.dev/v1/systemone' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: YOUR_OPERATION_KEY' \
--data-binary @request.json| Scénario | Clé et requête |
|---|---|
| Nouvelle décision ou nouvelle tâche | Créez un UUID neuf et une requête complète. |
Relance après un délai dépassé, une réponse perdue ou request_in_progress | Réutilisez la clé et la requête inchangées de l’opération existante. |
| Récupération après un crash ou un redémarrage | Chargez l’opération complète enregistrée durablement avant le premier envoi. |
| Autre clé d’API pour le même compte | Gardez la même clé d’opération : changer d’identifiants ne crée pas d’espace de noms distinct. |
Le service compare la requête canonique validée, y compris le modèle effectif, le contexte, les questions, les critères et les champs d’extension acceptés. Le formatage et l’ordre des clés d’objet n’importent pas ; l’ordre des tableaux, l’ordre de l’échelle de score, les valeurs de champ et la différence entre null et un champ omis importe. Une requête différente sous la même clé renvoie 409 idempotency_conflict.
Rejoué ou recalculé
| Opération existante | Réponse pour la même clé et le même corps | Conduite à tenir |
|---|---|---|
| Aucune opération conservée | Une nouvelle évaluation peut démarrer et débiter des crédits. | Conservez la clé jusqu’à ce que le résultat soit connu. |
| Encore en cours | 409 request_in_progress, avec Retry-After. | Attendez, puis relancez la même clé et le même corps. |
| Réussie | Renvoie le statut, le texte et les en-têtes autorisés enregistrés, sans nouvelle évaluation ni nouveau débit. | Utilisez le résultat récupéré. |
| Échouée et crédits restitués | 409 idempotency_failed. | Utilisez une nouvelle clé uniquement pour une nouvelle tentative délibérée. |
| Corps différent | 409 idempotency_conflict. | Restaurez le corps d’origine, ou attribuez une nouvelle clé à une opération réellement différente. |
| Réponse plus disponible | 410 idempotency_expired. | Vérifiez l’opération d’origine avant d’en lancer une autre. |
Un rejeu réussi inclut X-Idempotency-Replayed: true, X-System-One-Credits: 0 et l’X-Request-Id d’origine. Il réutilise la réponse enregistrée sans réévaluer le modèle. Un rejeu consomme toujours le quota de la plateforme, mais n’ajoute aucun nouveau débit.
La protection de rejeu des opérations terminées dure 24 heures à partir de la création de la requête. Passé ce délai, une ancienne clé peut démarrer une nouvelle opération facturable ; il n’existe pas de garantie de déduplication à vie. Une réservation expirée en cours de vol renvoie 409 request_expired.
Exemple avec le SDK
Reutilisez le même objet operation du démarrage rapide hébergé :
const result = await client.evaluate(operation.request, {
maxRetries: 0,
timeoutMs: 30_000,
headers: { 'Idempotency-Key': operation.idempotencyKey },
});Le SDK ne génère pas de clé d’idempotence automatiquement. Conservez la clé et la requête complète avant l’envoi, et ne générez pas une clé neuve dans le code de reprise : cela peut créer un autre débit.
Pour une reprise après un crash, votre application doit enregistrer durablement l’opération complète — clé et requête, y compris le modèle sélectionné — dans son enregistrement de tâche avant le premier envoi.
Erreurs fréquentes
- Une nouvelle clé à chaque reprise. Relancez avec la même clé et le même corps.
- Réutiliser une clé avec un corps différent. Cela renvoie
409 idempotency_conflict; une opération réellement différente exige une nouvelle clé. - Remplacer le modèle demandé par le nom résolu. Le modèle fait partie de l’identité de la requête ; le conserver est nécessaire pour récupérer l’opération.
- Confondre délai dépassé et absence de débit. Un délai dépassé ne prouve pas qu’aucun débit n’a eu lieu ; vérifiez l’usage avant de réessayer.
Pour l’index complet des codes, voir Codes d’erreur API. Pour la conservation des requêtes non résolues, voir Clé d’idempotence et Versioning API.
Liens internes : Référence API, Codes d’erreur API, Versioning API, Facturation & crédits, Documentation du SDK.