Troubleshooting

Every error response uses the OpenAI-style shape when possible:

{ "error": { "type": "...", "code": "...", "message": "..." } }

Start by logging the full body. The message field usually tells you the exact gateway or upstream reason.

401 authentication_error

The request reached token-hub but the key did not authenticate. Common causes:

1. Header is missing or malformed. It must read Authorization: Bearer $TOKENHUB_KEY.
2. Key was revoked from /keys.
3. Key belongs to a deleted account.
4. Someone pasted a truncated key.

Fix: issue a new key at /keys, update the client, and do not commit keys to source control. If you see 401 immediately after creating a new key, wait a few seconds for cache propagation and retry.

402 insufficient_balance

Your balance is below the estimated max cost of the request. We reject the call before forwarding to the upstream channel, so no tokens are consumed.

Fix: top up at /topup. Public checkout is USD-only through Stripe and starts at $5. Balance normally updates shortly after checkout.

429 rate_limit_exceeded

You exceeded the public default rate limit. The response may include Retry-After: N seconds.

Fix pattern:

import time, requests

def call(payload, key, retries=3):
    for i in range(retries):
        r = requests.post(
            "https://llm.sandboxclaw.com/v1/chat/completions",
            json=payload,
            headers={"Authorization": f"Bearer {key}"},
        )
        if r.status_code != 429:
            return r
        wait = int(r.headers.get("Retry-After", "1"))
        time.sleep(wait + i * 0.5)
    return r

For steady-state traffic above the published limit, contact support@sandboxclaw.com for a higher limit rather than retrying harder.

502 upstream_error

token-hub received an error from the selected upstream model channel. The error body includes the upstream reason when available.

Fix steps:

1. Retry with exponential backoff (1s, 2s, 4s). Most 502s are transient.
2. If another enabled model channel is available for your account, your application can choose to retry there.
3. If several routes fail at once, check the status page or email support with the request ID.

The request is not billed when we return 502 before a completed upstream response.

504 upstream_timeout

The upstream provider accepted the request but did not respond within the timeout window.

Common causes:

• Prompt is very long and the selected model is slow.
• max_tokens is very large and the model is taking the full budget.
• Upstream is under load.

Fix: reduce max_tokens, trim the prompt, or retry with backoff. A retry after 504 is usually safe.

Codex Responses API status

Codex uses the Responses API. Configure TokenHub with wire_api=responses, then choose a model enabled for the API key.

DeepSeek-TUI configuration

DeepSeek-TUI should use the OpenAI-compatible base URL with /v1 included:

export DEEPSEEK_API_KEY=$TOKENHUB_KEY
export DEEPSEEK_BASE_URL=https://llm.sandboxclaw.com/v1
export DEEPSEEK_MODEL=moonshot-v1-8k

If deepseek doctor reports authentication errors, verify that the environment has the full TokenHub key and that the key has balance.

Other useful codes

• 400 invalid_request_error - unknown model ID, malformed messages, prompt above the model context window, or unsupported field.
• 403 permission_denied - the requested route or model is disabled for your key or account.
• 404 not_found - endpoint or route not found.
• 500 internal_server_error - gateway-side failure. Safe to retry; open a ticket if it persists.

When in doubt

Email support@sandboxclaw.com with the full request ID header and the error body. We can look up the exact upstream response in the operational logs when available.