Skip to main content

Common Errors

This page documents common error responses you may encounter when working with the Netsmart General Purpose R4 FHIR API.

HTTP Status Codes​

The API uses standard HTTP status codes to indicate the success or failure of requests:

Status CodeDescription
200OK - Request successful
201Created - Resource created successfully
400Bad Request - Invalid request syntax or parameters
401Unauthorized - Authentication required or invalid
403Forbidden - Insufficient permissions
404Not Found - Resource not found
422Unprocessable Entity - Valid syntax but semantic errors
500Internal Server Error - Server error occurred

Common Error Scenarios​

Authentication Errors​

401 Unauthorized

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "security",
      "details": {
        "text": "Authentication required"
      }
    }
  ]
}

Cause: Missing or invalid authentication token Solution: Ensure valid authentication token is included in Authorization header

Resource Not Found​

404 Not Found

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

Cause: Requested resource ID does not exist Solution: Verify the resource ID and ensure the resource exists

Invalid Parameters​

400 Bad Request

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

Cause: Invalid search parameters or malformed request Solution: Check parameter names, values, and syntax against the CapabilityStatement

Extension Errors​

422 Unprocessable Entity

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "structure",
      "details": {
        "text": "Unknown extension URL"
      }
    }
  ]
}

Cause: Using unsupported or invalid extension URLs Solution: Verify extension support in the CapabilityStatement

Format Errors​

400 Bad Request

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "structure",
      "details": {
        "text": "Unsupported media type"
      }
    }
  ]
}

Cause: Unsupported Accept or Content-Type header Solution: Use supported formats: application/fhir+json, application/json, application/fhir+xml, application/xml

Troubleshooting Guide​

Step 1: Check CapabilityStatement​

Always start by retrieving the current CapabilityStatement to understand supported operations, parameters, and formats:

curl -X GET https://fhir.netsmartcloud.com/v4/metadata \
    -H "Accept: application/fhir+json"

Step 2: Validate Request Format​

Ensure your request includes proper headers and valid JSON/XML structure:

curl -X GET https://fhir.netsmartcloud.com/v4/Patient/123 \
    -H "Accept: application/fhir+json" \
    -H "Authorization: Bearer {your-token}"

Step 3: Check Resource Support​

Verify the resource type is supported by checking the CapabilityStatement rest.resource array.

Step 4: Validate Search Parameters​

Ensure search parameters are supported by checking the searchParam arrays for each resource type.

Step 5: Test with Minimal Request​

Start with the simplest possible request and add complexity incrementally.

Rate Limiting​

The API implements rate limiting to ensure fair usage:

429 Too Many Requests

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "throttled",
      "details": {
        "text": "Rate limit exceeded"
      }
    }
  ]
}

Solution: Implement exponential backoff and respect rate limit headers in responses.

Getting Help​

If you continue to experience issues:

  1. Check Documentation: Review the specific resource documentation for examples and requirements
  2. Validate Against CapabilityStatement: Ensure your request matches supported capabilities
  3. Contact Support: Reach out to Netsmart support through your designated support channels