Protocole d'erreur

Disponibilité de la fonction

Disponible

La fonction décrite existe et est testée ; la page dit aussi ce qu'elle ne fait pas.

Format des réponses d'erreur de l'API (RFC 9457), codes stables, catégories et statuts HTTP, identifiant de corrélation et règles de confidentialité.

Toute erreur de l'API NEXCLARA est rendue au format « Problem Details » de la RFC 9457, avec le type de contenu application/problem+json. Le format est le même pour toutes les opérations. Il porte un code stable : c'est le code, et non le texte, qui constitue le contrat.

Le corps d'une réponse d'erreur

Exemple synthétique : aucune donnée réelle

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "LINK_IDEMPOTENCY_KEY_REUSED",
  "category": "conflict",
  "correlation_id": "c0ffee00-0000-4000-8000-000000000000",
  "retryable": false,
  "context": {}
}

Champ	Sens
`type`, `title`	champs standard de la RFC 9457 ; `title` est le libellé HTTP, court et non traduit
`status`	statut HTTP de la réponse
`code`	code d'erreur stable, en majuscules ; il sert aussi de clé de traduction à l'interface
`category`	nature de l'erreur (voir ci-dessous)
`correlation_id`	identifiant de l'échange, identique à l'en-tête `X-Request-ID` de la réponse
`retryable`	vrai lorsque réessayer la même requête a un sens
`context`	précisions sûres : jamais de secret, jamais de donnée personnelle

Catégories et statuts HTTP

La traduction d'une catégorie en statut HTTP est faite à un seul endroit de la plateforme, et elle est fixe :

Catégorie	Statut	Quand
`validation`	422	entrée refusée ; la réponse permet au client de corriger
`not_found`	404	ressource inexistante dans le périmètre autorisé
`conflict`	409	état incompatible avec l'opération demandée
`authentication`	401	identité non établie : jeton absent, invalide, expiré
`permission`	403	identité établie, droit insuffisant
`configuration`	500	défaut de configuration du déploiement
`dependency`	503	dépendance indisponible (base de données, par exemple)
`integrity`	409	contrôle d'intégrité en échec
`internal`	500	défaut imprévu ; aucun détail n'est divulgué

Seule exception : une requête refusée avant d'atteindre une opération (une méthode HTTP non prise en charge, par exemple) garde le statut HTTP de ce refus, avec le code HTTP_ERROR ; une adresse inconnue rend NOT_FOUND.

Règles de confidentialité

aucun message technique brut (trace d'exécution, erreur SQL) ne quitte la plateforme : un défaut imprévu rend INTERNAL_ERROR, sans détail, et l'identifiant de corrélation permet l'investigation ;
pour une erreur de validation, seul l'emplacement des champs invalides est indiqué, jamais leur valeur, qui peut être une donnée personnelle ;
une ressource d'une autre institution répond exactement comme une ressource inexistante, et un refus de droit ne révèle pas l'objet visé ;
une connexion échouée rend la même réponse, quelle qu'en soit la cause.

Bonnes pratiques côté client

traiter les erreurs par leur code, jamais par leur title ;
ne réessayer que si retryable est vrai, avec un délai croissant ;
conserver correlation_id dans les journaux du système appelant, pour pouvoir le communiquer au support.

Encadré L'opération n'a pas abouti, avec la cause et la ligne Identifiant à citer au support suivie d'un identifiant. — Une erreur affichée avec l'identifiant de corrélation à citer au support. Extrait, environnement local. Capture du produit réel, données synthétiques.

Limite connue du contrat

Le contrat OpenAPI décrit encore les réponses 422 par le schéma générique du cadre applicatif, et n'énumère pas les codes d'erreur possibles de chaque opération. La réponse effective suit pourtant le format décrit ici. Un code renommé serait une rupture de contrat : les codes existants ne changent pas au sein d'une même version de l'API.

Informations sur cette page

État éditorial: Approuvé
Rédaction: Équipe produit NEXCLARA
Relecture: claude-relecteur-independant
Approuvé le: 16 octobre 2026
Révision: 2
Mise à jour: 15 octobre 2026
Classification: Public