Skip to main content

Common Errors

This page documents common errors and troubleshooting guidance for the Provider 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
  • Patient has not consented to data access
  • Requesting data outside of authorized patient 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 patient has provided consent for the requested data access
  • Check that you're only accessing data for the authorized patient
  • 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 patient
  • 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 patient
  • 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

Rate Limiting​

429 Too Many Requests​

HTTP Status: 429 Too Many Requests

Common Causes:

  • Exceeded API rate limits
  • Too many concurrent requests
  • Bulk operations without proper throttling

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

Common Integration Patterns​

Error Handling Best Practices:

// Example error handling pattern
try {
  const response = await fetch(fhirUrl, {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/fhir+json'
    }
  });
  
  if (!response.ok) {
    const errorBody = await response.json();
    console.error('FHIR Error:', errorBody);
    
    // Handle specific error types
    switch (response.status) {
      case 401:
        // Refresh token and retry
        break;
      case 429:
        // Implement backoff and retry
        break;
      case 500:
        // Log error and notify monitoring
        break;
    }
  }
  
  return await response.json();
} catch (error) {
  console.error('Network error:', error);
}

Logging and Monitoring​

Recommended Logging:

  • Request/response correlation IDs
  • HTTP status codes and response times
  • Error details from OperationOutcome resources
  • Token refresh events and failures

Monitoring Alerts:

  • High error rates (>5% of requests)
  • Authentication failures
  • Rate limiting events
  • Server errors (5xx responses)

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
    • 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