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

# Troubleshooting

> Solutions for common issues with the Public Records API

## "Authentication required. Provide Bearer token."

**Cause:** Missing or invalid Authorization header.

**Solution:** Include the Bearer token in the Authorization header:

```bash theme={null}
curl -X POST https://cra.pr.snh-ai.com/evaluate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"
```

***

## "Invalid or expired token"

**Cause:** JWT token has expired (default: 2 hours).

**Solution:** Get a new token from `/auth/token`:

```bash theme={null}
curl -X POST https://cra.pr.snh-ai.com/auth/token \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

***

## "Missing required field: search\_id"

**Cause:** Required field is missing from the request.

**Solution:** Ensure all required fields are included:

```json theme={null}
{
  "record": {
    "search_id": "76190bc0-e58c-494f-92c5-0c9a47389528",
    "search_date": "2025-04-30",
    "xml": "<ScreeningResults>...</ScreeningResults>"
  }
}
```

***

## "date\_of\_birth must be in YYYY-MM-DD format"

**Cause:** Date format is incorrect.

**Solution:** Use `YYYY-MM-DD` format:

```json theme={null}
{
  "candidate_info": {
    "date_of_birth": "1990-05-15"
  }
}
```

***

## "Court search ID and offense ID counts do not match the XML" (HTTP 500 on `/evaluate`)

**Cause:** A non-empty `record.cases[]` was sent with counts that do not match the parsed XML/record\_json. Common with filtered UBS payloads that include fewer court search IDs / offense ID rows than the full record (e.g., 17 court search IDs and 22 offense IDs when XML has 24 cases and 32 charges).

**Solution:** Either:

1. **Omit `cases[]` or send `cases: []`** — evaluate all offenses (recommended when you do not need explicit mapping), or
2. **Send the complete mapping** — one row per offense, with distinct court search ID count equal to XML case count and total offense ID row count equal to total offense count:

```json theme={null}
"cases": [
  { "court_search_id": "A", "offense_id": "1" },
  { "court_search_id": "A", "offense_id": "2" },
  { "court_search_id": "B", "offense_id": "3" }
]
```

Partial subsets are always rejected. This is not HTTP 422 on `/evaluate` — expect HTTP **500** with `data.status: "failed"`, `data.errors[]` containing `XML-Transformer HTTP error 422: Court search ID and offense ID counts do not match the XML: ...`, and `data.degradation.compliance_engine.status: "not_called"`. See [Error Handling → court search ID / offense ID count mismatch](/error-handling#court-search-id--offense-id-count-mismatch-500-on-evaluate).

***

## "Failed to parse XML data"

**Cause:** Invalid or malformed XML in the request.

**Solution:** Validate your XML before sending:

```python theme={null}
import xml.etree.ElementTree as ET
import io

def validate_xml(xml_string):
    try:
        ET.parse(io.StringIO(xml_string))
        return True
    except ET.ParseError as e:
        print(f"Invalid XML: {e}")
        return False
```

***

## Getting Help

If you encounter issues not covered here:

1. Check the [API Reference](/api-reference/overview) for endpoint-specific details
2. Verify your request format matches the [Code Examples](/examples)
3. Review the [Authentication Guide](/authentication) for token management

<snippet file="snippets/support.mdx" />