Common Errors

All error responses from the Provider Directory API follow the FHIR OperationOutcome format. This page provides examples of common error scenarios you may encounter and guidance on how to resolve them.

Error Response Schema

All error responses follow the FHIR OperationOutcome format:

OperationOutcome Structure

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error|warning|information",
      "code": "invalid|structure|required|value|invariant|security|login|unknown|expired|forbidden|suppressed|processing|not-supported|duplicate|multiple-matches|not-found|deleted|too-long|code-invalid|extension|too-costly|business-rule|conflict|transient|lock-error|no-store|exception|timeout|incomplete|throttled",
      "details": {
        "text": "Human readable description"
      },
      "diagnostics": "Additional diagnostic information",
      "location": ["FHIRPath expression indicating error location"]
    }
  ]
}

Common HTTP Status Codes

400 Bad Request

Example: Bad Request

HTTP/2 400 Bad Request
Content-Type: application/fhir+json;charset=UTF-8
X-Request-ID: f44edc90-ece1-425c-b3f3-d854f0ec8ebb

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

Common causes: Invalid search parameters, malformed requests, unsupported parameter values

Solutions:

• Verify parameter names match the FHIR specification
• Check resource-specific documentation for supported search parameters
• Ensure parameter values use correct format (e.g., dates, tokens)

403 Forbidden

Example: Access Denied

HTTP/2 403 Forbidden
Content-Type: application/xml

<Error><Code>AccessDenied</Code><Message>Access Denied</Message></Error>

Common causes: Invalid URL path, unsupported endpoint, malformed base URL

Solutions:

• Verify the base URL format: https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}
• Check that the tenant supports Provider Directory APIs
• Ensure resource type is supported (see supported resources documentation)

404 Not Found

Example: Resource Not Found

HTTP/2 404 Not Found
Content-Type: application/fhir+json;charset=UTF-8

{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"not-found","details":{"text":"Requested entity not found"}}]}

Common causes: Resource ID doesn't exist, unsupported resource type, inactive resources

Solutions:

• Verify the resource ID exists by searching first
• Check that the resource type is supported
• Ensure the resource is active (not deleted or inactive)

429 Too Many Requests

Example: Rate Limit Exceeded

HTTP/2 429 Too Many Requests
Content-Type: application/fhir+json;charset=UTF-8
X-RateLimit-Limit: [limit]
X-RateLimit-Remaining: 0
Retry-After: 60

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

Common causes: Exceeding rate limits, too many concurrent requests

Solutions:

• Implement exponential backoff retry logic
• Monitor X-RateLimit-* headers to track usage
• Reduce request frequency or batch operations
• Wait for the time specified in Retry-After header

500 Internal Server Error

Example: Server Error

HTTP/2 500 Internal Server Error
Content-Type: application/fhir+json;charset=UTF-8

{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"exception","details":{"text":"An unexpected error occurred"}}]}

Common causes: Server-side errors, temporary service unavailability

Solutions:

• Retry the request after a brief delay
• Check if the issue persists across multiple requests
• Contact Netsmart support if errors continue

Resource-Specific Errors

Organization Errors

Empty search results:

• Try broader search criteria (e.g., partial names)
• Check if data exists for the geographic region
• Verify organization type parameters (type=prov for providers)

Practitioner Errors

Specialty search issues:

• Use PractitionerRole resource for specialty searches, not Practitioner
• Verify specialty codes use NUCC taxonomy format
• Check for typos in practitioner names

Location Errors

Geographic search problems:

• Ensure state abbreviations are correct (e.g., CA not California)
• Verify postal code formats
• Use address-city instead of city parameter

PractitionerRole Errors

Invalid specialty codes:

• Use NUCC Provider Taxonomy codes (e.g., 207R00000X)
• Check the NUCC taxonomy for valid codes

Troubleshooting Guide

Error Code	Common Causes	Solutions
400	Invalid search parameters, malformed requests	Check parameter names and values against resource documentation
403	Invalid URL path, unsupported endpoint	Verify base URL and resource paths
404	Resource not found, unsupported resource type	Check resource ID exists, verify resource type is supported
429	Rate limit exceeded	Implement exponential backoff, reduce request frequency
500	Server error	Retry request, contact support if persistent

Best Practices for Error Handling

Parse OperationOutcome

Always check the issue array for detailed error information:

if (response.resourceType === 'OperationOutcome') {
  response.issue.forEach(issue => {
    console.log(`${issue.severity}: ${issue.details?.text || issue.diagnostics}`);
  });
}

Implement Retry Logic

Use exponential backoff for 429 and 5xx errors:

async function retryRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

Monitor Rate Limits

Track rate limit headers to avoid hitting limits:

const rateLimitRemaining = response.headers.get('X-RateLimit-Remaining');
const rateLimitReset = response.headers.get('X-RateLimit-Reset');

if (rateLimitRemaining && parseInt(rateLimitRemaining) < 10) {
  console.warn('Approaching rate limit, consider slowing requests');
}

Log Request IDs

Use X-Request-ID for troubleshooting with support:

const requestId = response.headers.get('X-Request-ID');
console.log(`Request ID for support: ${requestId}`);

Getting Help

If you continue to experience issues:

1. Check the OperationOutcome for specific error details
2. Verify your request against the resource documentation
3. Review this error guide for common solutions
4. Contact Netsmart support with the X-Request-ID from failed requests

For additional help, see:

• Provider Directory API Documentation
• Resource Documentation
• Postman Tutorial