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 fields401 Unauthorized: Missing or invalid token403 Forbidden: Insufficient scope or permissions422 Unprocessable Entity: FHIR validation failed
2. Parse the OperationOutcome
The response will include an OperationOutcome resource that provides structured details:
- Look at
issue[].diagnosticsfor human-readable explanations - Use
issue[].location[]to trace the exact field in error issue[].codeandseveritycan 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:
_lastUpdatedfilters to prevent duplicatesmeta.lastUpdatedto 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 [email protected]