This page provides examples of frequently encountered errors when working with Health Gorilla’s APIs. Each example includes the type of issue, the expected behavior, and how to resolve it.

All errors are returned with a standard HTTP status and a FHIR OperationOutcome response.

Missing Required Field

Example

POST /fhir/AllergyIntolerance
{
  "resourceType": "AllergyIntolerance",
  "code": {
    "text": "Penicillin"
  }
}

Response

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "required",
      "diagnostics": "The 'patient' field is required.",
      "location": ["AllergyIntolerance.patient"]
    }
  ]
}

Invalid Code Value

Example

{
  "resourceType": "Observation",
  "status": "final",
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "INVALID-CODE"
      }
    ]
  }
}

Response

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "The code 'INVALID-CODE' is not recognized for LOINC."
    }
  ]
}

Unauthorized Scope

Scenario

Client attempts to POST a resource with a read-only token.

Response

HTTP/1.1 403 Forbidden
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "forbidden",
      "diagnostics": "The current access token does not allow write access to this resource."
    }
  ]
}

Duplicate Resource Conflict

Scenario

Client tries to create a resource that already exists (e.g., same identifier).

Response

HTTP/1.1 409 Conflict
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "duplicate",
      "diagnostics": "A resource with this identifier already exists."
    }
  ]
}

Invalid Reference

Scenario

Client provides a reference to a nonexistent or deleted resource.

Response

 HTTP/1.1 422 Unprocessable Entity
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "diagnostics": "Patient/1234 could not be resolved."
    }
  ]
}