Glossary

FHIR OperationOutcome

A FHIR resource returned by a server to provide detailed information about the success or failure of an operation, including validation errors and warnings.

Get in touch Learn more

Stylish WeWork-like workspace with hot desks and document wall, professional searching through enterprise knowledge base on a mounted ultrawide display, warm industrial pendants overhead.

TRANSACTION FEEDBACK RESOURCE

What is FHIR OperationOutcome?

A detailed breakdown of the FHIR resource used to communicate the granular success, failure, and validation state of an API operation.

A FHIR OperationOutcome is a resource returned by a server to provide detailed, machine-readable information about the success or failure of a specific operation, including validation errors, business rule violations, and transient warnings. It serves as the standard feedback mechanism in RESTful FHIR interactions, replacing generic HTTP status codes with structured, coded issue components that precisely identify the nature of a problem.

Each OperationOutcome contains an array of issue elements, each with a severity (fatal, error, warning, information) and a code from a defined IssueType ValueSet, such as required, value, or not-found. This allows client systems to programmatically parse the response and trigger specific error-handling logic, distinguishing a missing required field from a terminology validation failure during a FHIR Validator check.

FHIR RESOURCE ANATOMY

Key Features of OperationOutcome

The OperationOutcome resource is the standard FHIR mechanism for conveying detailed success, warning, or failure information back to a client after an API interaction. It replaces generic HTTP status codes with structured, machine-readable issue details.

Issue Severity Classification

Every issue within an OperationOutcome carries a severity code that categorizes the gravity of the event. This allows client systems to programmatically differentiate between a hard stop and a non-blocking advisory.

fatal: The operation could not be completed, and the system is in an unstable state.
error: The operation failed, but the system state is stable (e.g., validation failure).
warning: The operation completed, but a potential issue exists (e.g., a deprecated code was used).
information: A purely informational note about the operation's outcome.

EXPLORE

Issue Type Taxonomy

The code element provides a fine-grained, machine-processable reason for the issue, drawn from a standard FHIR code system. This enables automated error handling logic without parsing human-readable text.

invalid: The content failed structural or business rule validation.
not-found: The specified resource or endpoint does not exist.
security: An authentication or authorization failure occurred.
processing: An internal server error or unexpected exception was encountered.
transient: A temporary failure, such as a timeout, suggests retrying the request.

EXPLORE

Diagnostics and Expression

To bridge the gap between machine and human readability, OperationOutcome provides two critical fields for debugging.

diagnostics: A plain-text string containing the full, technical error message, often including stack traces or internal error codes. This is intended for developers and system logs.
expression: A list of FHIRPath expressions that pinpoint the exact location of the error within the submitted resource. For example, Patient.name[0].given indicates the issue is with the first given name in the first name entry.

Operation Outcome vs. HTTP Codes

While HTTP status codes like 200 OK or 400 Bad Request provide a high-level summary, OperationOutcome delivers the granular detail required for healthcare interoperability.

HTTP 400: The response body MUST contain an OperationOutcome detailing the specific validation errors.
HTTP 422: Used specifically for unprocessable content where the syntax is correct but the clinical or business rules fail.
HTTP 500: The OperationOutcome should include a transient or processing issue code to guide client retry logic.

Validation Error Aggregation

A single OperationOutcome can bundle multiple independent issues, allowing a FHIR server to report all validation errors in one response rather than failing on the first error. This dramatically speeds up the developer feedback loop.

A single POST of a non-conformant Patient resource might return an OperationOutcome with 3 issues: a missing required name, an invalid telecom value, and a non-existent managingOrganization reference.
Each issue is a distinct object in the issue array, each with its own severity, code, and expression.

Terminology Service Integration

OperationOutcome is the standard response envelope for FHIR Terminology Service operations. When a code is validated against a ValueSet, the outcome communicates the result with precise detail.

A $validate-code operation returns an OperationOutcome where a code-invalid issue indicates the code is not in the ValueSet.
The display property mismatch between a provided code and the server's CodeSystem definition is reported as a warning, not an error, to support local display term variations.

ERROR HANDLING COMPARISON

OperationOutcome vs. HTTP Status Codes

Distinguishing between the transport-layer HTTP status code and the application-layer OperationOutcome resource for conveying detailed API operation results.

Feature	HTTP Status Code	OperationOutcome Resource
Layer of Communication	Transport Layer	Application Layer
Primary Purpose	Indicates general success or failure of the HTTP request	Provides detailed, machine-readable outcome of the FHIR operation
Granularity of Error	Coarse (e.g., 400, 404, 422)	Fine-grained, with specific issue codes and diagnostic text
Machine-Readable Detail
Human-Readable Detail	Limited to reason phrase	Rich 'diagnostics' field for developers and end-users
Required for FHIR Conformance
Contains Multiple Issues
Example of Use	200 OK, 201 Created, 400 Bad Request	issue.code = 'invalid', issue.diagnostics = 'Patient.name.given is required'

FHIR OPERATIONOUTCOME

Frequently Asked Questions

Clear answers to common questions about the FHIR OperationOutcome resource, its structure, and its role in API error handling and validation.

A FHIR OperationOutcome is a standard resource returned by a FHIR server to convey detailed information about the success or failure of an operation. It works as the primary error-reporting mechanism in the FHIR RESTful API, replacing traditional HTTP status code bodies with a structured, machine-readable format. When a server processes a request—whether a create, update, delete, or $validate operation—it populates an OperationOutcome with a list of issue components. Each issue contains a severity (fatal, error, warning, or information), a code that classifies the problem (e.g., required, value, invariant), and a human-readable diagnostics string. This allows client applications to programmatically parse and react to specific error conditions rather than relying on brittle string matching against unstructured messages.

Enabling Efficiency, Speed & Accuracy

Intelligent Analysis, Decision & Execution

We build AI systems for teams that need search across company data, workflow automation across tools, or AI features inside products and internal software.

Talk to Us

Search across company data

Give teams answers from docs, tickets, runbooks, and product data with sources and permissions.

Useful when people spend too long searching or get different answers from different systems.

Enterprise searchRAGPermissions

Automate internal workflows

Use AI to route work, draft outputs, trigger actions, and keep approvals and logs in place.

Useful when repetitive work moves across multiple tools and teams.

AI agentsWorkflow automationGovernance

Add AI to products and internal tools

Build assistants, guided actions, or decision support into the software your team or customers already use.

Useful when AI needs to be part of the product, not a separate tool.

AI integrationDecision supportModel routing

About the author

Prasad Kumkar

CEO & MD, Inference Systems

Prasad Kumkar is the CEO & MD of Inference Systems and writes about AI systems architecture, LLM infrastructure, model serving, evaluation, and production deployment. Over 5+ years, he has worked across computer vision models, L5 autonomous vehicle systems, and LLM research, with a focus on taking complex AI ideas into real-world engineering systems.

His work and writing cover AI systems, large language models, AI agents, multimodal systems, autonomous systems, inference optimization, RAG, evaluation, and production AI engineering.

Limited slotsGet a Free AI Consultation

How We Work

Custom AI workflows for your Business

One-fit-all AI don't work for modern businesses. At Inferensys, we aim to understand your business & custom requirements; which we use to define most efficient agentic workflows, the data, and the tools for your business.

Talk to Us

FHIR OperationOutcome

What is FHIR OperationOutcome?