API Reference

Error codes

All API errors return a JSON body with a code field and a human-readable message. Some errors include additional fields noted below.

Error shape

{
  "success": false,
  "error": {
    "code": "PAYER_AMBIGUOUS",
    "message": "Multiple catalog payers match payerName...",
    "candidatePayerLabels": ["Aetna Better Health", "Aetna Life Insurance"]
  }
}

Note: VALIDATION_ERROR includes an issues array instead of message.

All error codes

UNAUTHORIZEDHTTP 401

Cause: Missing or invalid Bearer token in the Authorization header.

Fix: Check that your API key is active and correctly formatted as Bearer <key>.

CLIENT_ID_REQUIREDHTTP 400

Cause: The X-Client-Id header is absent.

Fix: Add X-Client-Id: <clinic_uuid> to every request.

CLIENT_ID_INVALIDHTTP 400

Cause: X-Client-Id is present but not a valid UUID.

Fix: Copy the Client ID from the Clients page — it must be a UUID.

CLIENT_NOT_FOUNDHTTP 404

Cause: No clinic record exists for the provided Client ID.

Fix: Verify the UUID matches a client in your workspace.

CLIENT_INACTIVEHTTP 404

Cause: The clinic record exists but is marked inactive.

Fix: Re-activate the client in the Clients page.

WORKSPACE_MISMATCHHTTP 409

Cause: The Client ID belongs to a different workspace than the API key.

Fix: Ensure both the API key and Client ID are from the same workspace.

PAYER_NOT_FOUNDHTTP 404

Cause: No payer in the catalog matches the payerName you provided.

Fix: Try a more common spelling (e.g. "UnitedHealthcare" not "UHC"). Check the Payer catalog in your console.

PAYER_AMBIGUOUSHTTP 409

Cause: Multiple catalog payers fuzzy-matched payerName.

Fix: Use a more specific name. The error body includes a candidatePayerLabels array — pick one of those exact strings.

PAYER_ELIGIBILITY_NOT_SUPPORTEDHTTP 422

Cause: The payer is in the catalog but real-time eligibility checks are not enabled for it.

Fix: Contact support to request enablement for this payer.

VALIDATION_ERRORHTTP 400

Cause: The request body failed schema validation (e.g. missing required field, wrong type).

Fix: Read the issues array in the response body for field-level details.

IDEMPOTENCY_KEY_INVALIDHTTP 400

Cause: The Idempotency-Key header was provided but is not a valid UUID.

Fix: Generate a fresh UUID (e.g. crypto.randomUUID()) for each new logical request.

RATE_LIMITEDHTTP 429

Cause: Too many requests in a short window.

Fix: Back off and retry. Use exponential backoff starting at 1s.

REAL_CHECKS_DISABLEDHTTP 403

Cause: The deployment has live checks disabled via the ELIGIBILITY_REAL_CHECKS_DISABLED env var.

Fix: Use POST /api/eligibility/check/mock for testing, or contact the operator.

MOCK_ENDPOINT_DISABLEDHTTP 403

Cause: The mock endpoint is disabled via ELIGIBILITY_MOCK_ENDPOINT_DISABLED.

Fix: Contact the operator.

UNKNOWN_MOCK_FIXTUREHTTP 400

Cause: The mockFixture slug is not in the catalog.

Fix: Use one of the slugs listed on the mock endpoint reference page.

MISCONFIGUREDHTTP 500

Cause: A required server-side environment variable is missing or invalid.

Fix: Contact support with the traceId if available.