Note de référence
Erreurs UCP, reprises et idempotence en production
Distinguer erreurs de transport et résultats métier UCP, gérer 409, 429 et 503, puis reprendre sans doubler une transaction.
Publiée le . Rattachée à le guide d'implémentation UCP.
Une intégration UCP fiable distingue trois situations : le transport a échoué, la négociation a produit un résultat incompatible, ou la ressource métier demande une correction. Appliquer la même reprise à ces trois cas crée des boucles ou des doublons.
En bref
- HTTP reste le signal principal pour REST et MCP sur HTTP.
- Une incompatibilité de capacités peut répondre HTTP 200.
- Toute reprise d’une opération avec effet doit réutiliser sa clé d’idempotence.
Erreur de transport ou résultat de négociation ?
Les échecs de découverte signifient qu’un profil manque, reste inaccessible ou viole le schéma. Ils utilisent un statut de transport : 400 pour une URL invalide, 424 pour une dépendance inaccessible et 422 pour un profil mal formé ou une version non supportée.
Une intersection vide est différente. Le traitement a bien eu lieu, mais aucune capacité
commune n’existe. En REST, capabilities_incompatible peut donc apparaître dans une
réponse HTTP 200 avec ucp.status: "error". Vérifier seulement response.ok serait faux.
Le détail des codes de découverte figure aussi dans la note sur le manifeste UCP.
Quels statuts doivent déclencher une reprise ?
| Statut | Sens | Réaction |
|---|---|---|
| 401 | authentification absente ou invalide | renouveler ou demander l’identité |
| 403 | permissions insuffisantes | ne pas répéter sans changement de scope |
| 409 | même clé, payload différent | corriger la logique cliente |
| 429 | limite de débit | respecter Retry-After |
| 500 | erreur inattendue | reprise bornée selon l’opération |
| 503 | indisponibilité temporaire | respecter Retry-After |
Pour MCP sur HTTP, le statut HTTP est prioritaire et le code JSON-RPC complète le
diagnostic. La spécification recommande Retry-After en REST et
error.data.retry_after en MCP pour 429 et 503.
Comment reprendre sans doubler l’effet ?
Une clé d’idempotence identifie une tentative logique. Elle doit rester identique lors d’un timeout, d’une perte de réponse ou d’un 503. Le serveur renvoie alors la réponse conservée sans exécuter une nouvelle fois l’opération.
La clé doit être unique par client et type d’opération, avec au moins 128 bits d’entropie. Le serveur la conserve au minimum 24 heures. Si le stockage d’idempotence échoue, UCP demande un échec fermé en 503, car continuer exposerait à un double effet.
Réutiliser une clé avec un corps différent produit 409. Le client ne doit pas contourner ce conflit en générant immédiatement une nouvelle clé : il doit d’abord déterminer quel payload correspond à l’intention réelle.
Politique de reprise recommandée
- Classer l’opération comme lecture ou écriture.
- Pour une écriture, créer la clé avant le premier envoi et la journaliser avec le hash du payload, sans données sensibles.
- Sur 429 ou 503, attendre la durée indiquée, puis reprendre avec la même clé.
- Sur timeout, relire la ressource si l’API le permet avant de reprendre.
- Sur 409, arrêter l’automatisme et comparer les payloads.
- Borner le nombre de tentatives et prévoir un handoff humain.
Les messages métier demandent une autre logique
Dans Checkout, une erreur recoverable conduit à corriger les entrées puis appeler
Update Checkout. requires_buyer_input et requires_buyer_review imposent un passage
par continue_url. unrecoverable demande une nouvelle ressource ou un autre parcours.
Ces sévérités ne sont pas des consignes de reprise réseau. Une boucle exponentielle ne résoudra jamais une adresse manquante ou un consentement obligatoire. Leur place dans la machine à états est détaillée dans le cycle de vie du checkout.
Observabilité minimale
- statut HTTP et code UCP ou JSON-RPC ;
- identifiant de requête et hash de clé d’idempotence ;
- numéro de tentative et délai appliqué ;
- état métier avant et après l’appel ;
- décision finale : succès, abandon ou handoff.
Les journaux ne doivent contenir ni credential, ni instrument de paiement, ni donnée personnelle complète.
Sources
- UCP, Overview and Error Handling, release 2026-08-25
- UCP, Message Signatures and replay protection
- UCP, Checkout error handling
Revenir à le guide d'implémentation UCP · Toutes les notes · Read in English