Support teams live in the OperationOutcome payloads that reach them. They forward customer-reported issues, correlate them with server logs, decide whether a fix is a customer-side change or a code path bug, and communicate the resolution back. Every design choice on the outcome side either makes their job easier or harder. The patterns that help are cheap to add up front and expensive to add later. The site's OperationOutcome reader surfaces these fields when they are present. For the wider FHIR framing, related FHIR explainers has more.
Include A Stable Correlation Id
Every OperationOutcome should carry Resource.id populated with a stable, unique identifier the server can use to correlate with its own logs. Two-word rule: server logs and outcome share the same id.
Support engineers who have this id can search the server's logs directly. Without it, they are guessing based on timestamps and diagnostics text. That difference is minutes to hours per incident.
For the design-your-own side, designing your own OperationOutcome for a custom validator covers where the id fits.
Diagnostics Text That Says What To Do
Bad diagnostics: "Validation failed for element."
Good diagnostics: "Patient.gender must be one of male, female, other, unknown."
The difference is actionability. The good version tells the reader exactly what would satisfy the check. The bad version invites a support ticket.
Every message the support team forwards is a message the customer will read. Write for the customer.
Consistent Message Templates
Support teams triage by pattern. If the same error class produces the same diagnostics text every time, the pattern is easy to spot. If the text drifts because of dynamic values or version differences, every incident looks unique.
The mechanic: template with placeholders, keep the template stable, put the dynamic content in named slots. Support search by template hash first, drill into slots second.
Include The Server Version
Resource.meta.tag can carry a tag identifying the server version. Support engineers correlating an outcome with a server change need to know which version emitted it.
Without a version tag, "this error started three weeks ago" is anecdotal. With one, it can be mapped to a specific deploy.
Group Related Issues Together
When multiple issues arise from a single logical failure — a validator that finds five problems on one Patient — group them under a single OperationOutcome with multiple issue entries. The support engineer sees the pattern at once. Splitting them into five OperationOutcomes obscures the relationship.
For batch aggregation on the client side, aggregating OperationOutcomes across a batch is the entry.
Expose The Rule That Fired
For invariant failures and business-rule failures, name the rule. details.coding with a stable rule identifier lets support engineers find "all instances of rule-A-3 in the last week" in log search.
Without a rule identifier, the same rule fires from different code paths and produces slightly different diagnostics, and the correlation goes away.
Distinguish Customer-Facing From Internal
Some diagnostics are safe to surface to end users; some are not. Server-internal error details, stack traces, or database identifiers should not leak through the diagnostics field.
Two options: sanitize the diagnostics at emission, or mark internal-only fields with an extension so downstream systems can filter. The first is safer; the second is more flexible.
Log As Structured JSON
Every OperationOutcome logged internally should be structured JSON, not pretty-printed text. Support search over "all severity=error where issue.code=code-invalid on Patient.gender" only works if the fields are indexable.
For the alert-vs-log decision at the routing level, when an OperationOutcome should be an alert vs a log is the entry.
The Short Version
Correlation ids, actionable diagnostics, consistent templates, version tags, grouped related issues, named rules, sanitized customer text, structured logging. Each is small; together they turn support triage from hours to minutes.
Sources
- HL7 canonical OperationOutcome specification including - HL7 canonical OperationOutcome specification including Resource.id + meta fields