Common Errors

This page documents common errors and troubleshooting guidance for the Provider System Access API. Understanding these error scenarios will help you build more robust system 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
Invalid client credentials during token request

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 client credentials are correct for token requests
Check that Private Key JWT is properly signed (if using JWT authentication)
Confirm token was issued for the correct API endpoint
Verify system scopes are properly requested

403 Forbidden

HTTP Status: 403 Forbidden

Common Causes:

Insufficient system scopes in access token
Application not authorized for requested operation
IP address not whitelisted (if IP restrictions apply)
System-level permissions not granted

Example Response:

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

Solutions:

Verify your application has requested appropriate system scopes
Check that your application is registered for system access
Ensure IP address is whitelisted if restrictions apply
Review your application's system-level 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
Invalid bulk export parameters

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 bulk export parameter syntax
Ensure parameter values are properly URL encoded

404 Not Found

HTTP Status: 404 Not Found

Common Causes:

Resource ID does not exist
Incorrect resource type in URL path
Typo in resource ID or endpoint URL
Group ID not found (for group-level exports)

Example Response:

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

Solutions:

Verify the resource ID is correct and exists
Ensure you're using the correct resource type in the URL
Check Group ID for bulk export operations
Confirm the full endpoint URL is correct

Bulk Export Errors

429 Too Many Requests - Export Limit

HTTP Status: 429 Too Many Requests

Common Causes:

Too many concurrent bulk export requests
Export request rate limit exceeded
System resource constraints

Solutions:

Wait before submitting additional export requests
Check for existing in-progress exports
Implement proper request throttling

Export Job Errors

HTTP Status: 500 Internal Server Error (during export processing)

Common Causes:

Export job failed during processing
Data volume too large for single export
System resource constraints during export

Example Status Response:

{
  "transactionTime": "2023-10-01T10:00:00Z",
  "request": "https://fhir.example.com/Group/123/$export",
  "error": [
    {
      "type": "OperationOutcome",
      "url": "https://fhir.example.com/export-error.json"
    }
  ]
}

Solutions:

Check error details from the provided error URL
Consider breaking large exports into smaller date ranges
Retry the export request after addressing the error
Contact support for persistent export failures

Rate Limiting

429 Too Many Requests

HTTP Status: 429 Too Many Requests

Common Causes:

Exceeded API rate limits
Too many concurrent requests
System 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 for system operations

Server Errors

500 Internal Server Error

HTTP Status: 500 Internal Server Error

Common Causes:

Unexpected server-side error
Database connectivity issues
Temporary service disruption
Export processing failures

Solutions:

Retry the request after a brief delay
Check system status page for known issues
For bulk exports, check export status for specific error details
Contact Netsmart support if error persists

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

System-Specific Errors

Invalid Client Assertion

HTTP Status: 400 Bad Request (during token request)

Common Causes:

Malformed JWT in client_assertion
Invalid JWT signature
Expired JWT (check iat, exp claims)
Incorrect JWT audience (aud claim)
Missing required JWT claims

Example Response:

{
  "error": "invalid_client",
  "error_description": "Invalid client assertion JWT"
}

Solutions:

Verify JWT is properly formatted and signed
Check JWT claims (iss, sub, aud, iat, exp, jti)
Ensure JWT is not expired (exp claim)
Verify audience matches token endpoint URL
Confirm private key matches registered public key

Unsupported Grant Type

HTTP Status: 400 Bad Request (during token request)

Common Causes:

Using authorization_code instead of client_credentials
Typo in grant_type parameter
Application not configured for system access

Solutions:

Use grant_type=client_credentials for system access
Verify application is registered for system access
Check token endpoint URL is correct

Troubleshooting Tips

System Integration Debugging Steps

Verify Client Registration - Ensure application is registered for system access
Check Authentication Method - Confirm Private Key JWT or client secret setup
Validate System Scopes - Verify appropriate system/* scopes are requested
Test Token Acquisition - Ensure you can successfully obtain access tokens
Review CapabilityStatement - Check supported operations and parameters
Monitor Rate Limits - Implement proper throttling for system operations

Bulk Export Debugging

Check Export Status - Always poll status URL for export progress
Review Export Parameters - Validate _since, _type, and other parameters
Monitor Export Size - Large exports may take significant time
Handle Async Nature - Don't expect immediate results from bulk operations

Common Integration Patterns

System Authentication Pattern:

// Example system authentication
const getSystemToken = async () => {
  const tokenResponse = await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      'grant_type': 'client_credentials',
      'client_assertion_type': 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
      'client_assertion': signedJWT,
      'scope': 'system/Patient.rs system/Observation.rs'
    })
  });
  
  if (!tokenResponse.ok) {
    const error = await tokenResponse.json();
    console.error('Token error:', error);
    throw new Error(`Token request failed: ${error.error_description}`);
  }
  
  return await tokenResponse.json();
};

Bulk Export Pattern:

// Example bulk export workflow
const performBulkExport = async (accessToken) => {
  // 1. Initiate export
  const exportResponse = await fetch(`${baseUrl}/Group/123/$export`, {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/fhir+json',
      'Prefer': 'respond-async'
    }
  });
  
  if (exportResponse.status !== 202) {
    throw new Error('Export initiation failed');
  }
  
  const statusUrl = exportResponse.headers.get('Content-Location');
  
  // 2. Poll for completion
  let exportComplete = false;
  while (!exportComplete) {
    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
    
    const statusResponse = await fetch(statusUrl, {
      headers: { 'Authorization': `Bearer ${accessToken}` }
    });
    
    if (statusResponse.status === 200) {
      const exportResult = await statusResponse.json();
      // 3. Download files
      for (const file of exportResult.output) {
        await downloadExportFile(file.url, accessToken);
      }
      exportComplete = true;
    } else if (statusResponse.status !== 202) {
      throw new Error('Export failed');
    }
  }
};

Getting Help

Before Contacting Support

Review this error documentation for common solutions
Check the CapabilityStatement to verify supported operations
Test in preview environment to isolate the issue
Verify system registration and authentication setup
Gather relevant information:
- Request URL and headers
- Response status code and body
- Timestamp of the error
- Client ID and tenant information
- Export job IDs (for bulk export issues)

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

Authentication Guide - OAuth 2.0 implementation details
CapabilityStatement - Supported operations and parameters
System Access Tutorial - Step-by-step integration guide
Bulk Export Tutorial - Bulk data export walkthrough

Authentication Errors​

401 Unauthorized​

403 Forbidden​

Resource Errors​

400 Bad Request​

404 Not Found​

Bulk Export Errors​

429 Too Many Requests - Export Limit​

Export Job Errors​

Rate Limiting​

429 Too Many Requests​

Server Errors​

500 Internal Server Error​

502 Bad Gateway​

503 Service Unavailable​

System-Specific Errors​

Invalid Client Assertion​

Unsupported Grant Type​

Troubleshooting Tips​

System Integration Debugging Steps​

Bulk Export Debugging​

Common Integration Patterns​

Getting Help​

Before Contacting Support​

Contact Information​

Related Resources​

Authentication Errors

401 Unauthorized

403 Forbidden

Resource Errors

400 Bad Request

404 Not Found

Bulk Export Errors

429 Too Many Requests - Export Limit

Export Job Errors

Rate Limiting

429 Too Many Requests

Server Errors

500 Internal Server Error

502 Bad Gateway

503 Service Unavailable

System-Specific Errors

Invalid Client Assertion

Unsupported Grant Type

Troubleshooting Tips

System Integration Debugging Steps

Bulk Export Debugging

Common Integration Patterns

Getting Help

Before Contacting Support

Contact Information

Related Resources