Errors and exceptions

Response format

Errors raised while handling a FHIR resource request (for example an unknown id or an invalid search parameter) are returned as a FHIR OperationOutcome:

{
  "resourceType": "OperationOutcome",
  "issue": [{ "severity": "error", "code": "not-found", "diagnostics": "Encounter/abc not found" }]
}

Authentication and authorization failures (HTTP 401 and 403) are returned as a JSON object with statusCode, message and error; an insufficient-scope response also lists requiredScopes. Treat the HTTP status code as authoritative.

Status codes

Status	Meaning	What to do
200	Success.	—
202	Accepted (bulk export kickoff, or a bulk job still running).	Poll the status URL, honouring `Retry-After`.
400	The request is invalid: a malformed or unsupported search parameter, an invalid `_since`/`_type`/`_outputFormat`, or an unsupported `Prefer` value.	Correct the request. Retrying unchanged will fail again.
401	The access token is missing, malformed, expired, revoked or not issued for this server.	Refresh the access token with the refresh token; if that fails, send the user through authorization again.
403	The token is valid but does not allow this request: a missing scope, a resource outside the granted categories, a different patient than the one in context, or a user without permission to read that patient.	Request the missing scope, or do not retry. A refreshed token will not change the outcome.
404	The resource, bulk job or group does not exist, or you are not allowed to know it exists.	Check the id.
429 / 5xx	The server is busy or failed.	Retry later with exponential back-off.
503	A dependency (for example token validation) is temporarily unavailable.	Retry later.

Common situations

Situation	Result
Search for a patient other than the one in the token's context	403
Search without any patient parameter using a `patient/` scope	The search is limited to the patient in context
Use of a token after the patient revoked the application	401
Request for a resource type the server does not support	404
`create`, `update` or `delete`	Not supported; the API is read-only

Authorization server errors

Errors from the authorization and token endpoints follow RFC 6749 (error and error_description), for example invalid_grant for an expired or reused authorization code or a revoked refresh token, invalid_client for failed client authentication, and invalid_scope for a scope the client is not registered for.