Error Handling

The NeuralRev Integration API uses standard HTTP status codes to indicate the success or failure of requests.

HTTP Status Codes

Error Response Format

All error responses follow a consistent format:

{
  "error": "Human-readable error message",
  "statusCode": 400
}

For validation errors, additional field-level details may be included:

{
  "error": "Validation failed",
  "statusCode": 400,
  "details": [
    {"field": "first_name", "message": "Required"},
    {"field": "date_of_birth", "message": "Must be a valid ISO 8601 date"}
  ]
}

Common Error Scenarios

401 — Invalid or Missing API Key

{
  "error": "Invalid API key",
  "statusCode": 401
}

Causes:

• No x-api-key header or Authorization: Bearer token provided
• API key is malformed or does not exist
• API key has been deleted

Resolution: Verify your API key is correct and active in Settings > API Keys.

403 — Permission Denied

{
  "error": "API key is deactivated",
  "statusCode": 403
}

Causes:

• API key has been deactivated (but not deleted)
• The workspace associated with the key has been deactivated

Resolution: Reactivate the key or workspace in Settings.

400 — Referenced Entity Not Found

{
  "error": "Payer not found for id: PAYER-999",
  "statusCode": 400
}

Causes:

• Creating a patient with insurance that references a payer that doesn't exist
• Creating an encounter that references a patient, provider, or facility that doesn't exist

Resolution: Ensure referenced entities are created first. The recommended creation order:

1. Payers
2. Providers
3. Facilities
4. Patients (with insurance referencing payers)
5. Encounters (referencing patients, providers, facilities)

429 — Rate Limit Exceeded

{
  "error": "Too many requests. Please try again later.",
  "statusCode": 429,
  "retryAfter": 60
}

Causes:

• Exceeded 100 requests per minute from the same IP

Resolution: Wait for the retryAfter duration (in seconds), then retry. Implement exponential backoff in your integration.

404 — Resource Not Found

{
  "error": "Encounter not found",
  "statusCode": 404
}

Causes:

• Uploading a document to an encounter ID that doesn't exist
• Deleting a document that doesn't exist

Resolution: Verify the resource ID is correct. Ensure the encounter was created before uploading documents.

Best Practices

Retry Strategy

Implement exponential backoff for transient errors:

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error; // Don't retry 4xx errors (except 429)
    }
  }
  throw new Error('Max retries exceeded');
}

Error Categorization

Idempotency

All integration endpoints are idempotent by design (upsert semantics). If you're unsure whether a request succeeded, it's safe to retry — sending the same id will update the existing record rather than create a duplicate.

Monitoring

• Monitor for 401 errors to detect key rotation issues
• Alert on 429 errors to identify integration throughput problems
• Track 400 errors to catch data quality issues in your EMR sync
• All API calls are logged in the NeuralRev audit trail