Maximus FHIR API
ONC §170.315(g)(10)

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

StatusMeaningTypical causeHandling
200 OKSuccess—Parse the resource or bundle
202 AcceptedAccepted for async processingBulk export kick-offPoll the Content-Location URL
400 Bad RequestMalformed requestAn unknown search parameter, or an invalid parameter valueFix the request. Do not retry unchanged
401 UnauthorizedMissing, expired or invalid access tokenThe token has expired, or the header is malformedRefresh the token and retry once. If it fails again, re-authorize
403 ForbiddenAuthenticated but not permittedThe scope does not cover this resource, or the token's patient context does not match the patient requestedDo not retry. Check granted scopes and patient context
404 Not FoundNo such resourceA wrong id, or a resource the caller may not seeDo not retry
406 Not AcceptableUnsupported representationAn Accept header asking for XMLRequest application/fhir+json
429 Too Many RequestsRate limitedToo many requests in a short periodBack off exponentially before retrying
500 Internal Server ErrorUnexpected server fault—Retry with backoff. If it persists, contact support with the timestamp
503 Service UnavailableTemporarily unavailableMaintenance or overloadRetry 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."
    }
  ]
}
FieldData typeMeaning
issue.severitycodefatal, error, warning or information
issue.codecodeA machine-readable cause from the FHIR issue-type value set. Branch on this, not on the text
issue.diagnosticsstringHuman-readable detail, for logs and developers. Wording may change — never parse it
issue.expressionstringWhere present, a FHIRPath expression identifying the offending element

Common issue codes

CodeStatusMeaning
login401Authentication is required or the token is no longer valid
forbidden403The caller is authenticated but not permitted to read this data
not-found404The resource does not exist or is not visible to this caller
invalid400The request is structurally invalid
not-supported400 / 406The requested capability or format is not supported
throttled429Rate limit exceeded
exception500An unexpected server-side fault
403 is not a retryable error

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.

ClassStatusesCorrect response
Client error — your request is wrong400, 404, 406Do not retry. Log the OperationOutcome and fix the request.
Authorization error401, 403401: refresh once, then re-authorize. 403: do not retry; obtain the right scopes.
Transient error429, 500, 503Retry 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.
Never log a token or patient data

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.

Last updated 18 November 2026

Maximus EHR — documentation published for the ONC Health IT Certification Program.

See the API terms and conditions. Where this documentation and the Maximus EHR listing on the ONC Certified Health IT Product List differ, the CHPL listing governs.

© 2026 MaxRemind Inc. All rights reserved.