OperationOutcome — Le format standard d'erreur FHIR

Quand un serveur FHIR rejette une requête, valide un Bundle ou exécute une $operation, il répond avec une OperationOutcome. C'est le format normalisé de retour d'erreur, d'avertissement et d'information.

Objet de la ressource

OperationOutcome est le format universel par lequel un serveur FHIR communique le résultat d'une opération : erreur HTTP 4xx/5xx, succès partiel d'un Bundle de transaction, validation profil échouée, suggestion d'amélioration, etc. Chaque OperationOutcome contient une ou plusieurs issue, indépendantes les unes des autres.

Toute opération FHIR — REST CRUD, search, batch/transaction, $validate, $expand, $everything — peut renvoyer OperationOutcome dans le corps de la réponse HTTP ou dans le champ response.outcome d'un Bundle réponse.

Champs clés

Champ	Type	Cardinalité	Rôle
`issue`	BackboneElement[]	1..*	Obligatoire. Liste des problèmes signalés.
`issue.severity`	code	1..1	`fatal` \| `error` \| `warning` \| `information` \| `success`.
`issue.code`	code	1..1	Catégorie d'erreur. ValueSet `issue-type`.
`issue.details`	CodeableConcept	0..1	Détail codé + texte humain.
`issue.diagnostics`	string	0..1	Diagnostic technique (stack trace, pour debug).
`issue.location`	string[]	0..*	Chemin XPath/FHIRPath du nœud incriminé. Déprécié en R5 au profit de `expression`.
`issue.expression`	string[]	0..*	Expression FHIRPath identifiant l'élément en faute.

Severity et issue.code

Les cinq niveaux de severity :

fatal — l'opération n'a pas pu être réalisée, état indéterminé.
error — l'opération a échoué, état stable.
warning — l'opération a réussi mais avec un avertissement (ex : champ déprécié).
information — message non bloquant (ex : suggestion).
success — usage atypique, surtout pour les retours $validate.

Les principaux codes issue.code (ValueSet IssueType) :

Code	Sens
`invalid`	Contenu invalide (typage, structure).
`structure`	Erreur de structure JSON/XML.
`required`	Élément obligatoire manquant.
`value`	Valeur invalide (ex : code hors ValueSet).
`invariant`	Règle métier violée.
`security`	Erreur d'authentification ou d'autorisation.
`login`	Authentification requise.
`forbidden`	Accès refusé.
`not-found`	Ressource introuvable.
`duplicate`	Ressource déjà existante.
`conflict`	Conflit de version (ETag).
`processing`	Erreur générique de traitement.
`exception`	Exception inattendue (typiquement 500).
`timeout`	Timeout d'exécution.
`too-costly`	Requête trop coûteuse (ex : search non bornée).

Exemple JSON

Exemple d'OperationOutcome retourné par un serveur après une exception interne lors de la lecture d'un Patient référençant une Organization inconnue :

json operationoutcome-exception.json

{
  "resourceType": "OperationOutcome",
  "id": "exception",
  "text": {
    "status": "additional",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Le serveur a rencontré une condition inattendue.</p></div>"
  },
  "issue": [{
    "severity": "error",
    "code": "exception",
    "details": {
      "text": "Unexpected internal server error: invalid reference Patient/unknown"
    },
    "diagnostics": "Exception: java.lang.NullPointerException at PatientService.read:128",
    "location": ["Patient.managingOrganization"],
    "expression": ["Patient.managingOrganization"]
  }]
}

Pièges courants

Renvoyer du texte brut au lieu d'OperationOutcome — un serveur FHIR conforme retourne TOUJOURS un OperationOutcome sur erreur, jamais un message texte ou un HTML.
Fuite d'information dans diagnostics — éviter d'exposer une stack trace complète à un client externe : peut révéler version, framework, chemins serveur.
Confondre severity=fatal et error — fatal signifie état indéterminé, des side-effects partiels peuvent avoir eu lieu.
Mauvais issue.code — not-found doit accompagner un HTTP 404, forbidden un 403, conflict un 409…
Pas de location / expression — sans pointeur, le client ne sait pas quel champ corriger.

Ressources liées

Bundle — la réponse à une transaction inclut un OperationOutcome par entry en cas d'erreur partielle.
CapabilityStatement — déclare les codes d'erreur supportés.
OperationDefinition — décrit les opérations $xxx qui peuvent renvoyer OperationOutcome.

Fondamentaux

Standards

Messages phares

Outils