Healthcare / FHIR API

FHIR Error handling

FHIR R4

Handle FHIR errors consistently using OperationOutcome resources and HTTP status codes.

Authentication

OAuth 2.0

Bearer token

Scope

healthcare.read

Required

Standard

HL7 FHIR R4

FHIR R4

Rate limit

600 requests / min

Default

Response

Bundle / JSON

application/fhir+json

OperationOutcome

FHIR error

{
  "resourceType":"OperationOutcome",
  "issue":[{"severity":"error","code":"invalid","diagnostics":"Invalid patient identifier"}]
}

HTTP	Meaning
400	Invalid FHIR request
401	Authentication required
403	Insufficient permission or tenant access
404	Resource not found
409	Version/state conflict
422	FHIR validation failed
429	Rate limit exceeded
500	Server error

Field	Meaning
severity	fatal \| error \| warning \| information
code	FHIR issue code
details	Coded issue detail
diagnostics	Developer-readable context
expression	FHIRPath location

Validation failures return OperationOutcome issues pointing to the invalid fields/profile constraints.

Do not infer the existence of inaccessible resources from 403/404 behavior; clients should treat authorization outcomes conservatively.