Errors and exceptions
Every exception the API raises, the structure it returns, and how a client should handle each class of failure.
Every failure returns a standard HTTP status code and, for FHIR endpoints, an
OperationOutcome resource describing what went wrong. Authorization endpoint failures
return OAuth 2.0 error objects instead — those are listed on the
authorization page.
HTTP status codes
| Status | Meaning | Typical cause | Handling |
|---|---|---|---|
200 OK | Success | — | Parse the resource or bundle |
202 Accepted | Accepted for async processing | Bulk export kick-off | Poll the Content-Location URL |
400 Bad Request | Malformed request | An unknown search parameter, or an invalid parameter value | Fix the request. Do not retry unchanged |
401 Unauthorized | Missing, expired or invalid access token | The token has expired, or the header is malformed | Refresh the token and retry once. If it fails again, re-authorize |
403 Forbidden | Authenticated but not permitted | The scope does not cover this resource, or the token's patient context does not match the patient requested | Do not retry. Check granted scopes and patient context |
404 Not Found | No such resource | A wrong id, or a resource the caller may not see | Do not retry |
406 Not Acceptable | Unsupported representation | An Accept header asking for XML | Request application/fhir+json |
429 Too Many Requests | Rate limited | Too many requests in a short period | Back off exponentially before retrying |
500 Internal Server Error | Unexpected server fault | — | Retry with backoff. If it persists, contact support with the timestamp |
503 Service Unavailable | Temporarily unavailable | Maintenance or overload | Retry with backoff |
OperationOutcome
FHIR errors return an OperationOutcome. The issue array carries one or
more problems; each has a severity, a machine-readable code and a
human-readable diagnostics string.
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "forbidden",
"diagnostics": "The access token does not permit access to this patient."
}
]
}
| Field | Data type | Meaning |
|---|---|---|
issue.severity | code | fatal, error, warning or information |
issue.code | code | A machine-readable cause from the FHIR issue-type value set. Branch on this, not on the text |
issue.diagnostics | string | Human-readable detail, for logs and developers. Wording may change — never parse it |
issue.expression | string | Where present, a FHIRPath expression identifying the offending element |
Common issue codes
| Code | Status | Meaning |
|---|---|---|
login | 401 | Authentication is required or the token is no longer valid |
forbidden | 403 | The caller is authenticated but not permitted to read this data |
not-found | 404 | The resource does not exist or is not visible to this caller |
invalid | 400 | The request is structurally invalid |
not-supported | 400 / 406 | The requested capability or format is not supported |
throttled | 429 | Rate limit exceeded |
exception | 500 | An unexpected server-side fault |
A 403 means the token is valid but does not permit what you asked
for — usually a missing scope, or a patient-scoped token being used against a different
patient. Refreshing the token will not change the answer. Re-authorize with the scopes you need.
Exception handling
A robust client distinguishes three classes of failure and handles each differently.
| Class | Statuses | Correct response |
|---|---|---|
| Client error — your request is wrong | 400, 404, 406 | Do not retry. Log the OperationOutcome and fix the request. |
| Authorization error | 401, 403 | 401: refresh once, then re-authorize. 403: do not retry; obtain the right scopes. |
| Transient error | 429, 500, 503 | Retry with exponential backoff and jitter. Cap the attempts and surface a clear message. |
Recommended retry policy
attempt 1 -> wait 1s
attempt 2 -> wait 2s
attempt 3 -> wait 4s
attempt 4 -> wait 8s
then stop and surface the error
Add random jitter to each wait so that many clients
recovering from one outage do not retry in lockstep.
Error logs are a common source of PHI leakage. Log the status code, the issue
code and a correlation timestamp. Do not log the Authorization header, the request
body or the response body of a successful clinical call.
Reporting a problem
When reporting an API problem, include the UTC timestamp, the HTTP method and path with parameters,
the status code, the OperationOutcome issue.code and your
client_id. Do not include access tokens or patient data.