Conventions
Les identifiants, horodatages, la forme des erreurs, le versioning et les tentatives.
| Convention | Règle |
|---|---|
| Identifiants | UUID, opaques. Conservez-les entiers ; ne les analysez jamais et n'en raccourcissez jamais un |
| Horodatages | RFC 3339 en UTC, par ex. 2026-09-22T04:10:00Z |
| Champs inconnus | ignorez-les. De nouveaux champs de réponse et de nouvelles valeurs de statut peuvent arriver sans changement de version |
| Versionnage | le préfixe indique la version majeure. Une modification cassante reçoit un nouveau préfixe et est annoncée à l'avance |
| Erreurs | {"description": "…", "error": {"error_code": "…", "error_attributes": {…}}} — branchez-vous sur error.error_code, journalisez description, ne faites jamais de correspondance sur son texte. Voir Erreurs et limites |
| Tentatives de reprise | respectez Retry-After sur 429. Sur 5xx, réessayez avec une reprise exponentielle et du jitter |
Idempotence
Envoyez un idempotency_key à chaque exécution que vous lancez. C'est votre propre chaîne — un numéro d'épisode, un identifiant de tâche, tout élément stable pour cette unité de travail.
- La même clé avec le même corps renvoie l'exécution qui existe déjà, au lieu d'en démarrer une seconde.
- La même clé avec un corps différent est refusée avec
idempotency_conflict. Utilisez une nouvelle clé pour un nouveau travail.
Cela rend sûre une nouvelle tentative après un délai d'attente, ce qui fait la différence entre une seule exécution et un doublon qui vous est facturé.
Traçage
Chaque réponse comporte x-morphic-trace-id. Journalisez-le. Lorsque vous signalez un problème, cet identifiant nous permet de retrouver l'exécution en quelques secondes au lieu de vous demander une plage horaire.