When a Health Gorilla API request fails, the response includes a FHIR OperationOutcome resource with structured details about the error. This allows clients to parse, log, and respond to errors programmatically across all FHIR-based endpoints.

All error responses are returned as application/fhir+json.

Structure of OperationOutcome

The OperationOutcome resource contains an array of issue objects. Each issue provides information about a specific problem detected during request processing.

Common Fields

Field	Type	Description
`severity`	`code`	`fatal`, `error`, `warning`, or `information`
`code`	`code`	A coded classification of the issue (e.g., `invalid`, `required`, `forbidden`)
`diagnostics`	`string`	Human-readable explanation of the error
`location`	`string[]`	JSONPath or FHIR path to the field that caused the error (if applicable)
`details.text`	`string`	Optional short description of the error

Example Error Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/fhir+json
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "required",
      "diagnostics": "The 'patient' field is required.",
      "location": ["AllergyIntolerance.patient"]
    }
  ]
}

Severity Levels

Severity	Use Case
`fatal`	The request could not be processed at all
`error`	A problem that prevents the request from succeeding
`warning`	An issue that doesn't prevent success, but should be reviewed
`information`	Informational message that does not indicate a failure

Partial List of Issue Codes

Code	Meaning
`invalid`	General input validation error
`required`	Missing required field
`forbidden`	Access denied due to permissions
`not-found`	Referenced resource does not exist
`duplicate`	Duplicate resource or identifier
`conflict`	Data conflict or business rule violation
`structure`	Payload is structurally invalid
`processing`	Unexpected internal processing error

For a full list of FHIR issue codes, see the HL7 FHIR OperationOutcome specification.