Skip to main content

Common Errors

This page documents common errors and troubleshooting guidance for the Payer Patient Access API. Understanding these error scenarios will help you build more robust integrations and resolve issues quickly.

Authentication Errors​

401 Unauthorized​

HTTP Status: 401 Unauthorized

Common Causes:

  • Missing Authorization header
  • Invalid or expired access token
  • Malformed Bearer token format
  • Token issued for different API endpoint

Example Response:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "security",
      "diagnostics": "Invalid or missing authorization token"
    }
  ]
}

Solutions:

  • Ensure Authorization header is present: Authorization: Bearer {access_token}
  • Verify token is not expired and refresh if necessary
  • Confirm token was issued for the correct API endpoint
  • Check that token includes required scopes for the requested resource

403 Forbidden​

HTTP Status: 403 Forbidden

Common Causes:

  • Insufficient scopes in access token
  • Member has not consented to data access
  • Requesting data outside of authorized member context
  • Application not authorized for requested operation

Example Response:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "forbidden",
      "diagnostics": "Insufficient scope for requested resource"
    }
  ]
}

Solutions:

  • Verify your application has requested appropriate scopes during authorization
  • Ensure member has provided consent for the requested data access
  • Check that you're only accessing data for the authorized member
  • Review your application's registered permissions

Resource Errors​

400 Bad Request​

HTTP Status: 400 Bad Request

Common Causes:

  • Invalid search parameters
  • Malformed FHIR query syntax
  • Unsupported search parameter combinations
  • Invalid date formats or ranges

Example Response:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Invalid search parameter: 'invalid-param'"
    }
  ]
}

Solutions:

  • Review the CapabilityStatement for supported search parameters
  • Validate date formats (YYYY-MM-DD for dates, YYYY-MM-DDTHH:MM:SS for datetimes)
  • Check parameter spelling and case sensitivity
  • Ensure parameter values are properly URL encoded

404 Not Found​

HTTP Status: 404 Not Found

Common Causes:

  • Resource ID does not exist
  • Resource exists but is not accessible to the current member
  • Incorrect resource type in URL path
  • Typo in resource ID or endpoint URL

Example Response:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "diagnostics": "Resource not found or not accessible"
    }
  ]
}

Solutions:

  • Verify the resource ID is correct and exists
  • Ensure you're using the correct resource type in the URL
  • Check that the resource belongs to the authorized member
  • Confirm the full endpoint URL is correct

410 Gone​

HTTP Status: 410 Gone

Common Causes:

  • Resource has been deleted
  • Resource has been archived or moved
  • Historical data no longer available

Solutions:

  • Check if resource has been replaced with a newer version
  • Use search parameters to find current/active resources
  • Contact support if you believe this is an error

Payer-Specific Errors​

Member Context Errors​

HTTP Status: 403 Forbidden

Common Causes:

  • Attempting to access data for a different member
  • Member enrollment has expired or been terminated
  • Member not found in the payer system
  • Coverage period restrictions

Solutions:

  • Verify member ID matches the authorized member
  • Check member enrollment status and coverage periods
  • Ensure member has active coverage with the payer
  • Review member consent and authorization scope

Coverage and Benefits Errors​

HTTP Status: 404 Not Found or 400 Bad Request

Common Causes:

  • Requesting benefits for inactive coverage periods
  • Invalid benefit category or service type
  • Coverage not found for specified time period

Solutions:

  • Verify coverage periods and enrollment dates
  • Check benefit categories against payer's supported types
  • Use appropriate date ranges for coverage queries
  • Review member's coverage history

Rate Limiting​

429 Too Many Requests​

HTTP Status: 429 Too Many Requests

Common Causes:

  • Exceeded API rate limits
  • Too many concurrent requests
  • Member-specific rate limiting

Example Response:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "throttled",
      "diagnostics": "Rate limit exceeded. Please retry after 60 seconds."
    }
  ]
}

Response Headers:

  • Retry-After: 60 - Seconds to wait before retrying
  • X-RateLimit-Limit: 1000 - Requests per time window
  • X-RateLimit-Remaining: 0 - Remaining requests in current window

Solutions:

  • Implement exponential backoff retry logic
  • Respect the Retry-After header value
  • Reduce request frequency or implement request queuing
  • Contact support if you need higher rate limits

Server Errors​

500 Internal Server Error​

HTTP Status: 500 Internal Server Error

Common Causes:

  • Unexpected server-side error
  • Database connectivity issues
  • Temporary service disruption

Solutions:

  • Retry the request after a brief delay
  • Check system status page for known issues
  • Contact Netsmart support if error persists
  • Implement proper error handling and logging in your application

502 Bad Gateway​

HTTP Status: 502 Bad Gateway

Common Causes:

  • Upstream service unavailable
  • Network connectivity issues
  • Load balancer configuration problems

Solutions:

  • Retry the request after a brief delay
  • Check if the issue is widespread or isolated
  • Contact support if problem persists

503 Service Unavailable​

HTTP Status: 503 Service Unavailable

Common Causes:

  • Scheduled maintenance
  • System overload
  • Temporary service disruption

Response Headers:

  • Retry-After: 300 - Seconds to wait before retrying

Solutions:

  • Respect the Retry-After header if present
  • Check system status page for maintenance announcements
  • Implement circuit breaker pattern for resilience

FHIR-Specific Errors​

Invalid FHIR Accept Headers​

HTTP Status: 406 Not Acceptable

Common Causes:

  • Unsupported Accept header format
  • Missing FHIR content type specification

Solutions:

  • Use Accept: application/fhir+json for JSON responses
  • Use Accept: application/fhir+xml for XML responses
  • Avoid generic application/json for FHIR endpoints

Unsupported Operations​

HTTP Status: 405 Method Not Allowed

Common Causes:

  • Using unsupported HTTP method (POST, PUT, DELETE) on read-only API
  • Attempting operations not supported by the resource

Solutions:

  • Review CapabilityStatement for supported operations
  • Use only GET requests for Patient Access API
  • Check resource-specific operation support

Troubleshooting Tips​

General Debugging Steps​

  1. Check CapabilityStatement - Always start by reviewing what's actually supported
  2. Validate Tokens - Ensure tokens are valid and have appropriate scopes
  3. Review Request Format - Verify URL structure, headers, and parameters
  4. Check Response Details - Read OperationOutcome diagnostics for specific guidance
  5. Test in Preview - Use preview environment to isolate issues

Member-Specific Debugging​

  1. Verify Member Context - Ensure you're accessing data for the authorized member
  2. Check Coverage Periods - Validate member enrollment and coverage dates
  3. Review Consent Scope - Confirm member has consented to requested data access
  4. Test Member Authorization - Verify OAuth flow works for the specific member

Getting Help​

Before Contacting Support​

  1. Review this error documentation for common solutions
  2. Check the CapabilityStatement to verify supported operations
  3. Test in preview environment to isolate the issue
  4. Gather relevant information:
    • Request URL and headers
    • Response status code and body
    • Timestamp of the error
    • Member ID (if applicable)
    • Correlation ID if available

Contact Information​

  • Technical Support - Contact Netsmart support for integration assistance
  • Documentation Issues - Report documentation problems or suggestions
  • System Status - Check status page for known issues and maintenance