Troubleshooting

This page covers the most common issues you’ll encounter when calling the knowledge API, with error responses and steps to resolve them.

Invalid CCN format

The CCN must be exactly 6 digits. Letters, short strings, or non-numeric characters are rejected. Request:

curl -X POST https://api-dev.rcintell.com/v1/knowledge/resolve \
  -H "X-API-Key: $RCI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ccn": "1700"}'

Error response:

{
  "detail": [
    {
      "type": "string_pattern_mismatch",
      "loc": ["body", "ccn"],
      "msg": "String should match pattern '^\\d{6}$'"
    }
  ]
}

Solution: Ensure the CCN is exactly 6 numeric digits. Leading zeros matter — 050001 (California) is not the same as 50001. Pad with zeros if needed.

Unknown state code in CCN

The first two digits of the CCN must be a valid CMS state code (01-53). Error response:

{
  "ccn": "990001",
  "error": "Invalid CCN",
  "validation_errors": ["Unknown state code: 99"],
  "ccn_parsed": {
    "state": null,
    "facility_type": "Other Provider Type",
    "is_valid": false
  },
  "layers": [],
  "payment_estimate": null
}

Solution: Verify the CCN against the provider’s Medicare enrollment. State codes are CMS-specific and differ from FIPS or postal codes. For example, state code 17 is Kansas, not Illinois.

Valid state codes range from 01 (Alabama) to 53 (Wyoming). Puerto Rico is 40 and the Virgin Islands is 48.

Missing CPT for L5/L6

Layers L5 (Service Group) and L6 (Service) require a CPT code. If you request these layers without one, L5 defaults to E/M and L6 returns a skip notice. Request:

curl "https://api-dev.rcintell.com/v1/knowledge/layers/170001/l6" \
  -H "X-API-Key: $RCI_API_KEY"

Response:

{
  "layer": "l6_service",
  "data": {
    "layer": "l6_service",
    "note": "No CPT/HCPCS code provided; layer skipped"
  }
}

Solution: Include the cpt query parameter:

curl "https://api-dev.rcintell.com/v1/knowledge/layers/170001/l6?cpt=99213" \
  -H "X-API-Key: $RCI_API_KEY"

CPT code not in RVU table

If the CPT code exists but hasn’t been loaded into the RVU data, L6 returns a note rather than payment data. Response:

{
  "layer": "l6_service",
  "data": {
    "cpt": "99417",
    "note": "Code 99417 not in local RVU table — requires CMS data loader"
  }
}

Solution: This typically means the CMS MPFS data hasn’t been loaded for the current year. Contact your administrator to run the data loader, or verify the code is a valid CPT/HCPCS code that is payable under the MPFS.

Payer not recognized

L4 maps payer names through an alias system. Unrecognized payers fall back to generic commercial rules. Request:

curl "https://api-dev.rcintell.com/v1/knowledge/layers/170001/l4?payer=RandomInsuranceCo" \
  -H "X-API-Key: $RCI_API_KEY"

Response:

{
  "layer": "l4_payer",
  "data": {
    "payer_name": "Commercial",
    "payer_type": "private",
    "timely_filing": "Varies by contract (typically 90-365 days)",
    "prior_auth": "Required for many services — check specific plan",
    "appeals_levels": ["Internal appeal", "External review (state-mandated)"],
    "network_status_matters": true
  }
}

This is not an error — unrecognized payers receive the generic commercial profile. Use recognized names for specific rules:

Instead of	Use
`Blue Cross Blue Shield of Kansas`	`BCBS`
`UnitedHealthcare`	`UHC` or `United`
`Aetna Better Health`	`Aetna`
`Centers for Medicare`	`Medicare` or `CMS`

Invalid layer name

When requesting a specific layer, use the canonical names. Request:

curl "https://api-dev.rcintell.com/v1/knowledge/layers/170001/location" \
  -H "X-API-Key: $RCI_API_KEY"

Error response:

{
  "detail": "Invalid layer name"
}

Solution: Use one of the valid layer identifiers:

Accepted values	Layer
`l1`, `l1_location`	Physical Location
`l2`, `l2_facility_type`	Facility Type
`l3`, `l3_care_setting`	Care Setting
`l4`, `l4_payer`	Payer
`l5`, `l5_service_group`	Service Group
`l6`, `l6_service`	Service

Authentication errors

All knowledge endpoints require a valid API key in the X-API-Key header. Missing or invalid keys return 401 Unauthorized. Expired keys or keys without the knowledge scope return 403 Forbidden.

{
  "detail": "Invalid or missing API key"
}

Solution: Verify your API key is active and has the knowledge scope. Generate a new key from the admin dashboard if needed.

Get Started

Who is RCIntel for?

Policies

Knowledge Resolution

AI Agents

MCP Server

Facilities

Integrations

Free Tools

Healthcare Essentials

Platform

Troubleshooting

Invalid CCN format

Unknown state code in CCN

Missing CPT for L5/L6

CPT code not in RVU table

Payer not recognized

Invalid layer name

Authentication errors

​Invalid CCN format

​Unknown state code in CCN

​Missing CPT for L5/L6

​CPT code not in RVU table

​Payer not recognized

​Invalid layer name

​Authentication errors

Invalid CCN format

Unknown state code in CCN

Missing CPT for L5/L6

CPT code not in RVU table

Payer not recognized

Invalid layer name

Authentication errors