OPERATIONS & BILLING
Troubleshooting.
Common errors and how to fix them.
API errors
| Error | Likely cause | Fix |
|---|---|---|
| 401 Invalid token / Invalid API key | The key is missing, mistyped, or was replaced in the bot. | Copy it again from @outrunAPI_Bot -> My API key. Open a new terminal so the new environment variable is loaded. |
| Insufficient balance: remaining $... | Your Outrun Credit is too low for the request. | Add credit with crypto in the bot, or redeem a prepaid code (Redeem a code or /redeem CODE). |
| This API key has reached its spending limit | A spending limit is set on this key. | Contact support to change the limit. |
| 429 Too Many Requests | Rate limit reached. | Wait a few seconds and retry; send fewer requests at the same time. |
| 503 <model> is temporarily paused | This model is paused for maintenance. | Use another model, or check /status in the bot. |
| 500 / 502 / 504 | The upstream provider failed or timed out. | Retry after a short wait. If it keeps happening, check /status and contact support. |
| 404 Not found | Wrong base URL or path. | OpenAI-compatible apps use https://api.outrun.to/v1. Claude Code uses the bare host https://api.outrun.to. Gemini CLI uses https://api.outrun.to/v1/gemini-cli. Never add /chat/completions or /messages to a base URL. |
| 403 "Just a moment..." page | A Gemini request went to https://api.outrun.to/v1beta/... , which the firewall blocks. | Set GOOGLE_GEMINI_BASE_URL (or your SDK base URL) to https://api.outrun.to/v1/gemini-cli. |
| Model not found / invalid model | The model ID is misspelled (IDs are case-sensitive). | Copy the ID from Models & Pricing or GET /v1/models. |
App-specific issues
| App | Symptom | Fix |
|---|---|---|
| Codex | API_KEY_REQUIRED, 401, or "requires a newer version of Codex" | Codex is not getting the key. Set OUTRUN_API_KEY and keep env_key = "OUTRUN_API_KEY" in [model_providers.outrun]; on Windows you can use experimental_bearer_token instead. Do not put the key in auth.json or OPENAI_API_KEY. Update Codex with npm install -g @openai/codex. |
| Codex | Websocket or streaming connection errors | Add supports_websockets = false to the [model_providers.outrun] block. |
| Claude Code (Windows) | 401 even though the key is correct | Remove ANTHROPIC_API_KEY from your user environment variables and from ~/.claude/settings.json; keep only ANTHROPIC_AUTH_TOKEN set to your Outrun key. Close every terminal and VS Code window, then restart. |
| Claude Code | Still uses an Anthropic account | Run /logout, restart Claude Code and accept the custom API key when asked. |
| Claude Code | Errors that name a Haiku model | Set ANTHROPIC_DEFAULT_HAIKU_MODEL to claude-sonnet-5 in the same place as your other ANTHROPIC_ variables. |
| Gemini CLI | Asks you to sign in with Google | Set "security": {"auth": {"selectedType": "gemini-api-key"}} in ~/.gemini/settings.json, or choose "Use Gemini API Key". |
| Zo Computer / Cline | Connection check or Test fails | Base URL must be exactly https://api.outrun.to/v1 with nothing added after /v1; choose the OpenAI (OpenAI Compatible) format. |