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. - For a graphical interface, install OpenCode Desktop or run
opencode web. For Kimi Code, runkimi web. - 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. - Follow the guide for each client: some require
/v1, a full operation URL, or only the host. - Enter your API Key as described in the client guide. For authentication errors, check for conflicting Keys in configuration files, settings, and environment variables.
Client limitations
- In Cursor, explicitly select the configured model for testing instead of
Auto. Custom Keys apply to chat models; Tab completion uses built-in models. See the official guide for supported models and account limits. - After enabling a provider in CCSwitch, open Codex or Claude Code and send a message.
- Enter connection details in the model, provider, or API Key settings page. Menu locations can vary by version.
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 | Increase the delay between retries and limit attempts |
502 / 503 / 504 | Service temporarily unavailable or response timed out | Wait briefly and retry |
Retry a failed request
After a timeout or disconnect, the original call may still have completed. Before retrying:
- Review the response and usage records to check whether the request completed.
- For configuration errors such as
400or401, apply the fix above before sending again. - For
429or temporary service failures, increase the delay between attempts and set a maximum retry count.
Each retry is a new call and may incur additional charges.