Search
K
< Back

Error Handling

FHIR-based queries may return errors that affect data retrieval, paging, or downstream workflows. Health Gorilla APIs use standard HTTP status codes and include an OperationOutcome resource in the response body to explain issues in detail. Understanding how to interpret and respond to these errors is essential for building reliable data access workflows.

Common HTTP Error Codes

Status CodeMeaningNotes
400 Bad RequestThe request was malformed or included invalid parametersCheck for missing or unsupported query parameters
401 UnauthorizedAuthentication failed or access token is invalidEnsure the token is present, not expired, and correctly scoped
403 ForbiddenThe token is valid but the action is not permittedCheck OAuth scopes, user role permissions, and record-level restrictions
404 Not FoundThe requested resource or patient does not existMay indicate an invalid patient ID or missing resource
409 ConflictThe request conflicts with the current state of the resourceOften caused by duplicate data or idempotency key reuse
422 Unprocessable EntityThe server understood the request but could not process itPayload may be missing fields, invalid, or reference a non-existent resource
429 Too Many RequestsRequest rate limits were exceededSee the Retry-After header to determine wait time before retrying
500 Internal Server ErrorUnexpected error in Health Gorilla backendRetry or contact support if persistent
502 Bad GatewayCommunication problem between servers in the request chainUsually transient, retry after delay
504 Gateway TimeoutThe request took too long to completeRetry with async request model if supported

Interpreting OperationOutcome

Each error response includes a FHIR OperationOutcome resource that describes the issue.

Key fields include:

  • issue.severity: usually error or fatal
  • issue.code: a standardized error code (e.g., invalid, forbidden, not-found)
  • diagnostics: human-readable explanation of the error

Example:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Parameter 'date' is not supported for this resource type"
    }
  ]
}

Retry and Recovery Guidance

  • Include the X-Request-Id header in all requests to support debugging.
  • Log the X-Hg-Request-Id and any returned correlation ID for tracking.
  • Retry logic should be applied only for transient errors such as 429 or network timeouts.
  • Do not retry automatically on errors such as 400, 403, or 404 without user or system review.

R4 v STU3 Considerations

  • The structure of OperationOutcome is the same across R4 and STU3.
  • Supported error codes and diagnostics may vary slightly depending on version and resource type.
  • Rate limiting (429) applies in both versions but thresholds and enforcement may differ by environment.