Erreurs

Toute erreur — y compris celles levées avant que votre requête n'atteigne le handler — est renvoyée sous forme de document Problem Details, avec le type de contenu application/problem+json. Il n'existe pas de seconde forme d'erreur, plus ancienne, à gérer en parallèle.

{
  "type": "errors/not-found",
  "title": "Demande de congé introuvable",
  "detail": "Aucune demande de congé ne correspond à l'identifiant fourni.",
  "status": 404,
  "instance": "/api/v1/client/…",
  "traceId": "00-4bf92f…-00f067aa0ba902b7-01"
}

Champ	À quoi il sert
`type`	C'est là-dessus qu'on branche. Un slug stable, insensible à la formulation et à la langue.
`title` / `detail`	Lisibles, localisés. À afficher, jamais à parser.
`status`	Même valeur que le code HTTP.
`instance`	Le chemin qui a produit l'erreur.
`traceId`	À communiquer au support — il identifie votre requête exacte dans nos traces.

Types d'erreur

`type`	Statut	Signification
`errors/bad-request`	400	La requête est malformée ou échoue à la validation.
`errors/forbidden`	403	Authentifié, mais pas autorisé à faire cela.
`errors/not-found`	404	La ressource n'existe pas, ou ne vous est pas visible.
`errors/conflict`	409	La requête entre en conflit avec l'état courant.
`errors/module-disabled`	403	Aucun établissement de votre périmètre n'a activé le module requis par cette opération. Il suffit qu'un seul l'ait activé pour que l'opération réponde, sur cet établissement seul.
`errors/perimeter-unresolved`	403	Aucun établissement que votre accès désigne n'existe encore : tous ont été fermés. Distinct de `module-disabled`, et pour une raison pratique — il n'y a rien à souscrire ici. Votre mandat doit être repointé sur des établissements existants, ce que seule la société cliente peut faire.
`errors/feature-not-in-plan`	403	L'offre souscrite par la société n'inclut pas cette fonctionnalité.
`errors/gone`	410	La ressource a existé et n'existe plus — un fichier stocké au-delà de sa durée de rétention. Délibérément pas un `404`, qui dirait qu'elle n'a jamais existé et vous ferait chercher une erreur dans votre propre code. Redemandez-la plutôt que de réessayer celle-ci.
`errors/payload-too-large`	413	La réponse que nous devrions vous envoyer est trop volumineuse pour être servie — un document stocké au-delà de la taille que cette API accepte de matérialiser. À ne pas confondre avec `quota/payload-too-large`, qui porte sur le corps que vous envoyez : ici, il n'y a rien à réduire de votre côté.
`errors/service-unavailable`	503	La ressource existe et relève bien de votre périmètre, mais une dépendance nécessaire pour la produire n'a pas répondu. Réessayez après `Retry-After` secondes.
`errors/internal`	500	Quelque chose a échoué de notre côté. Réessayez plus tard, en citant le `traceId`.
`scopes/insufficient`	403	Le jeton n'a pas le scope exigé — le `detail` le nomme. Voir Authentification.
`quota/exceeded`	429	Limite de débit du plan atteinte. Voir Limites de débit.
`quota/payload-too-large`	413	Le corps de la requête dépasse le plafond de votre plan.
`idempotency/key-required`	400	L'opération exige un `Idempotency-Key`. Voir Idempotence.
`idempotency/in-progress`	409	La même clé est déjà en cours de traitement.

Ce qu'une erreur ne contient jamais

Les corps d'erreur ne portent aucune donnée personnelle. Une défaillance inattendue est nettoyée en un errors/internal générique plutôt que d'exposer un message interne — un 500 ne vous apprendra donc pas grand-chose, et c'est voulu. C'est à cela que sert le traceId : il permet au support de retrouver le contexte complet sans le faire transiter sur le réseau.

Réessayer

Statut	Réessayer ?
`400`, `403`, `404`, `409`	Non. Corrigez la requête.
`410`	Non — la ressource a définitivement disparu. Redemandez-en une ; réessayer cet identifiant ne réussira jamais.
`413`	Non — mais regardez lequel. `quota/payload-too-large` porte sur le corps de votre requête : envoyez moins. `errors/payload-too-large` porte sur un document stocké que nous ne pouvons pas servir, et rien de votre côté ne peut y changer quoi que ce soit.
`429`	Oui, après `Retry-After` secondes.
`503`	Oui, après `Retry-After` secondes. Plafonnez vos réessais : le statut ne dit pas si la dépendance va revenir, donc une ressource définitivement perdue serait sinon réessayée indéfiniment. Ouvrez un ticket plutôt que de boucler.
`500`, `502`, `504`	Oui, avec un backoff exponentiel.

Pour une écriture qui n'est pas naturellement idempotente, réessayez avec le même Idempotency-Key — c'est ce qui rend le réessai sûr. Voir Idempotence.