An OperationOutcome carries two very different fields that both look diagnostic: severity and diagnostics. They serve different purposes, and consulting them in the wrong order is a common time-waster. Severity is a machine-readable enum that decides the next step. Diagnostics is free text that helps a human understand what happened. Read them in that order and the triage takes a minute; read them backwards and it takes an hour. The site's OperationOutcome reader surfaces both. For the wider FHIR framing, the broader clinical interoperability hub has more.
Severity Is The First-Order Decision
Four values, in order of urgency:
fatal— the operation stopped and nothing succeeded. Rollback anything client-side and stop.error— a specific entry failed; the operation may have partial results.warning— the operation succeeded and something is worth noting.information— the operation succeeded and here is context; usually log-only.
Every OperationOutcome has at least one issue, and the highest severity across issues sets the tone. A response with one error and ten warnings is an error response; the warnings do not soften it.
For the base pattern, reading an OperationOutcome for the first time is the entry.
Route Based On Severity, Not Diagnostics
The first mistake teams make: read diagnostics text, decide next step from it. That works for one incident. It does not work at scale — diagnostics text varies per server, per version, per operation. Severity is stable.
A client that dispatches on severity has a small dispatch table. A client that dispatches on diagnostics text has a growing pile of string-matching rules that break every time a server updates.
Diagnostics Is Human Detail, Not Machine Decision
Diagnostics answers "why" for a human reader. It is verbose, prose-shaped, and often specific to the exact scenario. Read it when you need it — during debugging, during support, during incident review. Do not build automation on top of it.
The exception: your own servers where you own the diagnostics text and can promise stability. Even then, prefer a stable machine-readable field.
Details Is The Bridge
details.text is a shorter human explanation than diagnostics. details.coding is where a server may provide a stable coded reason beyond the base code field. When a server uses details.coding consistently, that is the field to dispatch on.
Most servers do not. Check the server's documentation for its OperationOutcome conventions before assuming.
Code Is The Categorical Reason
issue.code is the second-order machine-readable field after severity. It categorises the reason — invalid, required, structure, business-rule, and so on. Combined with severity, the pair is enough for most dispatch decisions.
For the enumeration, issue.code vocabulary and what it actually means walks through each entry.
Response Handling By Severity
- Fatal — rollback, alert, do not retry
- Error — surface to caller, may retry after correction
- Warning — log, decide whether to alert
- Information — log only
That is the four-line dispatch table every FHIR client should have. For the alert-vs-log question specifically, when an OperationOutcome should be an alert vs a log is the deep dive.
What Happens On 200 With Warnings
An OperationOutcome with warnings can accompany a 200 OK. The write succeeded but the server wants to flag something. Callers that ignore the body on 200 miss the warning. The right pattern: always parse the body when the response is FHIR-shaped.
For the specific pattern of what a 200-with-warning looks like across servers, the reader at /diagnostics/read-outcome-payload/ is the fast check.
The Short Version
Severity picks the branch. Code picks the sub-branch. Details.coding is the stable-if-provided bridge. Diagnostics is human detail, read last. Every OperationOutcome fits that pattern; every dispatch built on it survives server updates.
Sources
- HL7 canonical issue-severity value set defining - HL7 canonical issue-severity value set defining fatal/error/warning/information