# Troubleshooting > Start with the symptom you see. Each fix keeps API-credit and token-budget routes separate. ## Start here [**“Gateway unreachable” or timeout**Confirm the client is using the base URL for both its protocol and the key’s billing mode. Then run scalemax doctor.](https://docs.scalemax.pro/docs/troubleshooting#gateway-unreachable)[**Models load, but a request fails**Check the selected model, available balance, provider scope, and the exact error code returned by the test request.](https://docs.scalemax.pro/docs/troubleshooting#models-load-request-fails)[**“Terminal tools are not available”, or the agent only plans**Switch Roo Code to Code or Debug mode, or Cline to Act mode. Read-only modes cannot carry out the task; your key is fine.](https://docs.scalemax.pro/docs/troubleshooting#coding-tool-symptoms)[**Roo Code stuck at “API Request…”**On recent VS Code versions, run npx scalemax@latest fix-roo (Windows PowerShell: npx.cmd scalemax@latest fix-roo), then Developer: Reload Window.](https://docs.scalemax.pro/docs/troubleshooting#roo-stuck-api-request)[**“fetch failed” in the CLI**Run the local connection checks, then verify that a VPN, proxy, firewall, or incorrect system clock is not blocking TLS.](https://docs.scalemax.pro/docs/troubleshooting#fetch-failed)[**Payment, coupon, or redeem problem**Keep the order ID and open the matching recovery steps. Never pay the same pending invoice twice.](https://docs.scalemax.pro/docs/troubleshooting#billing-problems) ## Gateway unreachable or timed out Do not copy a URL from another key or client. Native Anthropic clients append `/v1/messages` themselves, while OpenAI-compatible clients expect a base URL ending in `/v1`. **Start with the key you bought.** Choose its billing path, then the row that matches your client's protocol. | Key type | Protocol | Use with | Base URL | | --- | --- | --- | --- | | API Credit | OpenAI-compatible Chat Completions or Responses | Codex, OpenCode, Cursor, Roo Code, SDKs, and direct HTTP | `https://api.scalemax.pro/v1` | | API Credit | Native Anthropic Messages | Claude Code, Claude Desktop, and native Messages clients | `https://api.scalemax.pro` | | Token Budget | OpenAI, Gemini, Grok, Qwen, DeepSeek, or Local Models token pack · OpenAI-compatible API | Codex, OpenCode, Cursor, Roo Code, SDKs, and direct HTTP | `https://api.scalemax.pro/token/v1` | | Token Budget | Claude token pack · Native Anthropic Messages | Claude Code, Claude Desktop, and native Messages clients | `https://api.scalemax.pro/token` | | Token Budget | Claude token pack · OpenAI-compatible adapter | OpenCode, Cursor, Roo Code, compatible SDKs, and direct HTTP | `https://api.scalemax.pro/token/v1` | **The protocol decides whether the client field ends in `/v1`.** OpenAI-compatible clients use a base URL ending in `/v1`. Native Anthropic clients use the origin only, without `/v1`, because they append `/v1/messages` themselves. A Claude token key therefore reaches `/token/v1/messages` when the native client builds its request. Use the key's matching billing surface and only models returned by its authenticated catalog. A Claude token key and an OpenAI token key are provider-scoped; neither can be swapped onto the other's models. Claude Desktop is a native Anthropic client with its own third-party inference settings. Follow the [Claude Desktop guide](https://docs.scalemax.pro/docs/manual-configuration/claude-desktop); it does not read Claude Code's configuration. 1. Choose API Credit or Token Budget in the selector above. 2. Copy the URL for the protocol your client uses. 3. Keep the credential kind set to a static API key and use the Bearer authentication scheme when the client asks. 4. Save the settings, restart the client, and run the local check: **macOS / Linux** ```bash scalemax doctor ``` **Windows PowerShell** ```powershell scalemax.cmd doctor ``` Claude Desktop has separate third-party inference settings and does not read Claude Code configuration. Follow the [Claude Desktop guide](https://docs.scalemax.pro/docs/manual-configuration/claude-desktop). ## Models load, but a request fails Successful model discovery proves that the endpoint can authenticate the key. Inference can still fail if the chosen model is outside that key's scope, the key lacks available balance, or the request has an invalid field. In Roo Code and Cline, enter the raw`sm_live_…` value only. Do not add a custom`Authorization` or `x-api-key`header: the client creates its own Bearer header, and a stored override can make discovery succeed while inference fails. 1. Fetch the authenticated model list and copy an exact model ID: **macOS / Linux** ```bash scalemax models ``` **Windows PowerShell** ```powershell scalemax.cmd models ``` 2. Check the dashboard for remaining credit or tokens and any temporary balance reservation from another in-flight request. 3. Expand the client's provider error and look up its machine-readable code in [Error Codes](https://docs.scalemax.pro/docs/error-codes). 4. If support is required, share the `X-Request-Id`, model ID, timestamp, and status code. Never share the full API key. ### Model unavailable If the client says the selected model is unsupported or temporarily unavailable, choose only a model returned by the live command above. The list is filtered to the active key's provider scope. ### 429 or temporary balance reservation Honor `Retry-After` and let the current request finish before retrying. Do not start several parallel retries. If the error is exhausted quota rather than a temporary reservation, top up the same key first. ## Symptoms in your coding tool ### “Terminal tools are not available”, or the agent only plans The agent is in a read-only mode; it is not failing to reach ScaleMax. Of Roo Code's built-in modes, only **Code** and **Debug** can run terminal commands. Ask mode is read-only and Architect mode can only edit Markdown files, so in those modes Roo answers that terminal tools are not available and the command never runs. Cline edits files and carries out the task only in **Act** mode; in Plan mode it looks through the project and proposes a plan without changing anything. - **Roo Code:** switch the mode selector to Code (or Debug) and send the task again. - **Cline:** switch from Plan to Act mode. Nothing is wrong with your key, so there is no need to replace it or run `scalemax` again. Setup details are in the [Roo Code](https://docs.scalemax.pro/docs/manual-configuration/roo-code) and [Cline](https://docs.scalemax.pro/docs/manual-configuration/cline) guides. ### Roo Code stuck at “API Request…” On recent VS Code versions, Roo Code 3.54 cannot find VS Code's relocated ripgrep, so every task hangs at “API Request…” with `Could not find ripgrep binary`, whatever model you choose. Patch the installed extension, then run **Developer: Reload Window**: **macOS / Linux** ```bash npx scalemax@latest fix-roo ``` **Windows PowerShell** ```powershell npx.cmd scalemax@latest fix-roo ``` Windows PowerShell blocks npm’s .ps1 launchers by default (“running scripts is disabled on this system”), so these commands use the .cmd launcher: npx.cmd, npm.cmd, scalemax.cmd. In Command Prompt you can leave out .cmd. The manual alternative and the undo command are in the [Roo Code guide](https://docs.scalemax.pro/docs/manual-configuration/roo-code#stuck-at-api-request). ## “fetch failed” in the CLI **macOS / Linux** ```bash scalemax doctor ``` **Windows PowerShell** ```powershell scalemax.cmd doctor ``` - Confirm the computer date, time, and time zone are correct. - Temporarily test without a VPN or HTTPS-inspecting proxy if your organization permits it. - Confirm a firewall or security product is not blocking `api.scalemax.pro`. - Run `scalemax login` again only if the doctor reports that the stored key is missing or invalid. A browser being online does not prove that a terminal or desktop app can reach the same TLS endpoint through its own proxy settings. ## Invalid or expired key A `401 invalid_credentials` means the credential is missing, malformed, revoked, or being sent to the wrong billing surface. Re-authenticate locally: **macOS / Linux** ```bash scalemax login scalemax doctor ``` **Windows PowerShell** ```powershell scalemax.cmd login scalemax.cmd doctor ``` If the key was lost, use the customer dashboard's key replacement flow. It revokes the old secret and transfers the remaining entitlement to the replacement. ## Payment, coupon, or redeem problem - **Payment pending:** keep the private return page and wait for confirmation. Do not pay the same invoice again. - **Coupon rejected:** confirm the selected gateway, active dates, and your allowed use count. - **Redeem code rejected:** select an active paid standard OpenAI, Claude, or combined key. Trial, DeepSeek, and other exact-model keys are not eligible. - **Low balance:**use the dashboard's top-up action to add credit or compatible tokens to the same key. See [Billing, coupons, and redeem codes](https://docs.scalemax.pro/docs/billing) for the complete checkout and recovery flow. Contact [ScaleMax support](https://docs.scalemax.pro/docs/support) with the ScaleMax order ID if a confirmed payment still shows **Needs review**.