# Troubleshooting

Symptoms, causes, fixes. Every row names a status code or error `code` where one exists.

| Symptom | Likely cause | Fix |
|---|---|---|
| `401 authentication_error` | key missing, malformed, or revoked | check the `Authorization` header; api-keys |
| `403 permission_error` | key lacks a scope | add the scope; teams-and-scopes |
| `402 insufficient_credits` | balance exhausted | top up; pricing-and-credits |
| `429` on every call | concurrency too high | cap client concurrency; rate-limits |
| Search stuck in `running` | deep review in progress | check `progress` on jobs; expect minutes |
| `409 document_not_ready` | asked a question before parsing finished | wait for `succeeded`; documents |
| `422 document_unparseable` | scanned without OCR, encrypted, or corrupt PDF | OCR it, or remove encryption |
| Answer has no citations | question not answerable from the given sources | widen the scope, or use searches instead of chats |
| Citation has no `locations` | we do not hold that paper's PDF | fall back to text search; citation-highlights |
| Highlights land in the wrong place | bbox mapping or page rotation | re-read the locator contract in citation-highlights |
| Streaming connection drops mid-answer | proxy idle timeout | heartbeats + reconnect; streaming-deep-review |
| Charged twice for one action | retry without an idempotency key | send `Idempotency-Key`; conventions |
| Extraction row has `null` everywhere | the field descriptions are too vague | rewrite descriptions; extraction-schema |

## Still stuck

Include the `X-Request-Id` and the resource ID. See get-support.