> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rcintell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors and solutions when using the knowledge resolution API

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:**

```bash theme={null}
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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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.

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

## 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:**

```bash theme={null}
curl "https://api-dev.rcintell.com/v1/knowledge/layers/170001/l6" \
  -H "X-API-Key: $RCI_API_KEY"
```

**Response:**

```json theme={null}
{
  "layer": "l6_service",
  "data": {
    "layer": "l6_service",
    "note": "No CPT/HCPCS code provided; layer skipped"
  }
}
```

**Solution:** Include the `cpt` query parameter:

```bash theme={null}
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:**

```json theme={null}
{
  "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:**

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

**Response:**

```json theme={null}
{
  "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:**

```bash theme={null}
curl "https://api-dev.rcintell.com/v1/knowledge/layers/170001/location" \
  -H "X-API-Key: $RCI_API_KEY"
```

**Error response:**

```json theme={null}
{
  "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

<Warning>
  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`.
</Warning>

```json theme={null}
{
  "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.