DEEPTHROAT DEVELOPER GUIDE
Errors & troubleshooting
Find the cause of a failed request and the next step to resolve it.
HTTP status codes
| Status | Meaning | Next step |
|---|---|---|
400 | Invalid request or parameter | Check the JSON, format, and model capabilities |
401 | Missing or invalid key | Check the header and key |
402 | Credit or token allowance exhausted | Fund the key or start an hourly plan |
403 | Access denied or disabled key | Check key access |
404 | Unknown model or endpoint | Use the exact model ID and correct base URL |
429 | Rate limit reached | Wait; honor Retry-After when provided |
500–503 | Request or service failure | Read the error and retry transient failures with backoff |
Connection checklist
- 1Confirm that the API key is enabled and has credits or an active plan.
- 2Fetch /v1/models with the same key to check authentication and exact model IDs.
- 3For Chat Completions and Responses use the /v1 base URL; for Claude Code use the API origin.
- 4Select your harness’s documented API format. Codex requires Responses with HTTP streaming.
- 5Inspect the error response and Activity before changing models or retrying.
Retry behavior
Use backoff for transient network errors and rate limits. Fix invalid credentials, insufficient credits, or unavailable models before retrying. Preserve conversation and tool-call IDs when continuing an agent task.
Claude Code: selected model issue
Use an exact Claude model ID from
/v1/models, check ANTHROPIC_BASE_URL, and verify the key with the same terminal credentials. A display label such as “Opus” is not the gateway’s model ID.