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.