Errors, limits, and retries
Resolve client installation, configuration, status-code, and retry issues in one place.
Installation
- Command not found after installation: close and reopen the terminal, then confirm that the npm global executable directory is on
PATH. - Client surfaces differ: OpenCode CLI, desktop, and local Web use the same configuration; Kimi Web is provided by the CLI.
- A VS Code extension does not read its configuration: confirm that the official extension is installed, save the file, and fully quit and reopen VS Code.
Configuration and protocols
Use the relevant client guide as the source for the Base URL, API Key, and model name.
- Codex uses OpenAI Responses. Its Base URL ends in
/v1andwire_apiisresponses. - Claude uses Anthropic Messages. Its Base URL does not include
/v1; the client requests/v1/messages. - Other OpenAI Compatible clients use the address ending in
/v1. - Write the Key directly to the corresponding client configuration or settings UI. Remove conflicting old Keys, environment variables, or providers.
Client limitations
- Cursor requires Cursor Pro for a custom API Key, Base URL, and named model. Cursor Free and
Autocannot configure or verify a custom route. - CCSwitch writes and switches providers; it is not an agent. Confirm the final reply in Codex or Claude.
- Menu labels can vary across GUI-client versions. Use the model, provider, or API Key settings page, not the account sign-in page.
HTTP status
| Status | Common cause | Action |
|---|---|---|
400 | Invalid body, conflicting fields, or protocol mismatch | Fix the configuration or request; do not replay unchanged |
401 | Missing, malformed, or unread API Key | Save the Key again and restart the client |
402 | Insufficient usable balance | Review balance and recharge |
403 | Invalid Key, account policy, CIDR, spend, or API URL restriction | Check the Key, account policy, and address |
404 | Wrong Base URL suffix, operation path, or model name | Correct the address for the protocol and verify the public model |
405 | Unsupported protocol or operation | Select an operation supported by the client and route |
413 | Request body or file exceeds a limit | Reduce the input or file |
429 | RPM, concurrency, or account-capacity limit | Wait and use bounded backoff |
502 / 503 / 504 | Service temporarily unavailable or response timed out | Wait briefly and retry |
Retry deliberately
After a timeout or disconnect, the original call may still have completed. Before retrying:
- Confirm the status of the original request.
- Decide whether duplicate output and charges are acceptable.
- Apply bounded backoff only for
429and temporary dependency failures. - Treat the retry as a new independent call.