# Troubleshooting

1. CLI: run `betterfilings doctor --json`, `betterfilings usage --json`, and `betterfilings setup --json`. Hosted MCP: call `usage_get` and `research_help`.
2. Separate authentication failure, quota exhaustion, request throttling, missing coverage, unavailable artifact, source failure, and local processor failure. They require different actions.
3. Preserve the complete structured error, warnings, filing ID, artifact key, execution mode, and retry guidance.
4. For an unchanged hosted retry, reuse its `requestId`. Use a new UUID only for a new operation. Follow `nextCall` exactly when work is still running.
5. On direct-source 403 or 429, honor `Retry-After` and back off. Use only an advertised managed route; do not invent URLs.
6. If local processing is unavailable, use the plan printed by `betterfilings setup --json` and the recovery steps at [betterfilings.com/cli/setup](https://betterfilings.com/cli/setup). Hosted MCP processing remains a separate execution path where enabled.

An empty result, a search miss, and an unreadable document are different outcomes. State which one occurred and what scope was actually checked.