When an API request fails, Health Gorilla provides detailed error responses using standard HTTP status codes and the FHIR OperationOutcome format. This page offers practical tips for diagnosing and resolving common integration issues.

1. Inspect the HTTP Status Code

Start by checking the status code in the API response:

400 Bad Request: Likely malformed input or missing fields
401 Unauthorized: Missing or invalid token
403 Forbidden: Insufficient scope or permissions
422 Unprocessable Entity: FHIR validation failed

2. Parse the OperationOutcome

The response will include an OperationOutcome resource that provides structured details:

Look at issue[].diagnostics for human-readable explanations
Use issue[].location[] to trace the exact field in error
issue[].code and severity can help categorize the problem

3. Enable Logging and Audit Trails

Log each API request and response, including:

Request method, endpoint, and payload
Response status and body
Timestamps and correlation IDs if applicable

Use logs to trace failed requests and detect recurring patterns.

4. Validate Access Tokens

Verify that your access token:

Is active and not expired
Was issued with the correct scopes
Belongs to a user or client authorized for the requested resource

Use /oauth/info to inspect token details. For example: GET /oauth/info?access_token=your_token.

5. Test with Known Good Payloads

If you're unsure whether an error is related to your input, try using a known valid payload from the API documentation or Postman collection. Compare the structure, required fields, and code systems.

6. Use Timestamps to Debug State

When polling or receiving webhook payloads, include:

_lastUpdated filters to prevent duplicates
meta.lastUpdated to compare versions of the same resource

7. Contact Support with Context

If the error persists after debugging:

Include the full request and response (redact PHI)
Include timestamps, resource IDs, and token scopes
Contact your Client Success Manager or support@healthgorilla.com