Troubleshooting by symptom

Record the time, client, model, HTTP status, and request ID when available. Never send a full API key or full prompt.

401: missing or invalid API key

Cause: The Authorization header, environment variable, or config file does not contain the expected key, or the old key was disabled.

Action: Copy the key again from the console, check the variable name and header, then rotate the key if needed.

Cause: The key's group is disabled, has no usable model, or the client is calling a protocol that the group does not expose.

Action: Check the group in API Keys and the model in live pricing. Claude Code uses Messages; Codex uses Responses.

Cause: The Base URL contains a duplicated or missing /v1 or /v1beta suffix, or the client uses the wrong protocol path.

Action: Copy the endpoint from Use API Key instead of composing it manually. The default OpenAI-compatible endpoint is https://ai1api.com/v1.

Cause: Too many requests arrived in a short period, or the client opened too much concurrency.

Action: Reduce concurrency and retry with exponential backoff. Check balance and group capacity before continuing.

Cause: An upstream provider or routing path is temporarily unavailable.

Action: Record the time, model, and request ID, then retry after a short delay. Contact support with the redacted error if it persists.

Cause: The client, proxy, or network is not handling SSE/WebSocket correctly, or the upstream switched during the request.

Action: First retry with stream=false, then check proxy timeouts and client versions. Enable Codex WebSocket only for groups that support it.

Cause: The upstream requires a newer Claude Code release.

Action: Upgrade Claude Code using the client message, reopen the terminal, and retry. Do not change the model name to bypass a version check.

Cause: macOS blocked an app installed outside the App Store.

Action: Open System Settings → Privacy & Security, choose Open Anyway for the blocked app, and restart it.