Troubleshooting

Find the category, then the row that matches what you see. The full status-code table, retry rules, and what to include in a report are in Error codes and retries.

The gateway returns Simplified Chinese, Traditional Chinese, English, Japanese, or Spanish text based on the Accept-Language header, and English when the header is not set. The tables quote the English text.

Keys, balance, and permissions

Symptom	Cause	What to do
401 "Missing API key" "Invalid API key" "API key has expired"	No key sent, copied incompletely or with extra spaces, or deleted, disabled, or expired	Re-copy the full key from API Keys in the console; create a new one if needed
402 "Insufficient balance" "API key quota exhausted" "Member quota exhausted" "Department quota exhausted"	Account balance, key quota, or enterprise member or department quota is insufficient	Add funds or adjust the quota first; 402 does not resolve on its own, so do not retry in a loop
A video submission returns 402 "Insufficient balance: available …"	Not enough balance to reserve when the video task was submitted	Add funds, then resubmit; do not retry in a loop
403 "This account has been disabled" "This member account has been disabled" "This member is not allowed to use the group bound to this API key" "API key is not bound to any group, please contact the administrator" "Image generation is not enabled for the current group"	Account, member, or group settings	Contact your administrator; do not retry
404 "The group this API key belongs to has been taken offline and no longer serves requests…"	The key's group has been discontinued	Create a new key in a currently sold group and replace the old one

Models and paths

Symptom	Cause	What to do
404 "The current group does not support the requested model: X" "The group this API key belongs to does not provide the requested model…"	The ID is not in any of this key's groups, is misspelled, or is a decommissioned ID left in your client config	Copy a full ID from `GET /v1/models` with this key; if it is missing, add the model's group to the key. Do not retry automatically
404 "This API path is not supported by the current platform"	A Claude key called an OpenAI-protocol endpoint	Switch Claude to the Anthropic protocol
Same as above	The Anthropic Base URL has an extra `/v1` (`/v1/v1/messages`)	Leave `/v1` out of the Base URL
Same as above	The path is not exposed, such as `/v1/dashboard/billing/*`, `/v1/files`, `/v1/batches`, `/v1/embeddings`	Check balance with `GET /v1/usage` or the console
Same as above	Codex web search called `/v1/alpha/search`	This 404 does not affect conversations
A video endpoint returns 404 "This API path is not supported by the current platform"	The video path is wrong	Per the Video API, submit with `POST /v1/video/generate` and poll `GET /v1/video/tasks/{task_id}`

Request content

Symptom	Cause	What to do
400 "Failed to read request body" "Request body must be a JSON object with valid field types" "Missing required field: model" "messages must be a non-empty array"	The body is incomplete or has invalid fields	Check the JSON and `Content-Type`
413 "Request body exceeds the size limit (60 MB)"	The body exceeds 60 MB, usually base64 images or video	Compress large files, or pass a URL when the model supports it
400 for exceeding context length (text varies by model)	History, attachments, and `max_tokens` together exceed the context window	Trim the history or start a new conversation, and reduce `max_tokens`
400 "Invalid `signature` in `thinking` block" "duplicate `thinking.signature`"	Claude's thinking history was rewritten, spliced, or duplicated	Resend the last thinking block unchanged, with its signature; never merge it or reuse it across models. Else restart without thinking history
400 "No tool call found for function call output" "No tool output found for function call"	Tool results and calls are not paired: `tool_call_id` / `call_id` mismatch, or one side is missing	Return one result per tool call with its ID unchanged; trim history in pairs
400 "Unsupported parameter: …"	The model does not accept a parameter you sent	Remove it; on the Responses API, use `max_output_tokens`, not `max_tokens`

Images and video

Symptom	Cause	What to do
400 content rejected by a safety policy (for example "Your request was rejected by the safety system.")	The prompt or a reference asset triggered the content-safety policy	Revise the prompt or asset; resending unchanged is rejected again
400 invalid image parameters (for example "size … is not valid")	The size, tier, or count is outside what that model supports	Adjust the value for that model per the Image API
400 "media_download_failed"	A reference image or video URL is not publicly reachable	Use an HTTP(S) URL that downloads without signing in
400 "InputImageSensitiveContentDetected.PrivacyInformation"	Seedance 2.0 runs privacy detection on real-person references passed directly	Upload with `POST /v1/sd/assets` first, then reference `asset://asset-id`; see the Video API
An async task poll returns `status: "failed"` (for example "the prompt was rejected by content moderation; rephrase it and submit again")	The reason is in `error.message`, with no `code`; not billed	Fix what the message says, then resubmit; see Error codes and retries
You need the actual charge for an async task	Returned in the task query once the task finishes	Read top-level `usage.cost_usd` (the USD amount deducted from your balance), `usage.cost` (the same charge in CNY), and `usage.currency` (`0` for an uncharged failure); finished tasks in a task list carry them too. See the Video API

Rate limits, timeouts, and disconnects

Symptom	Cause	What to do
429 "User concurrency limit reached, please retry later" "API key concurrency limit reached, please retry later"	In-flight requests exceed the account's or key's concurrency limit	Queue on the client and retry after `Retry-After`; limits are in Concurrency, timeouts, and billing
429 "… are currently rate limited, please retry later" 502 "… service is temporarily unavailable, please retry later" 503 "No … is available right now, please retry later" 503 "The request could not be completed right now, please retry later" 504 "… request timed out, please retry later" 503 "Authentication service is temporarily unavailable, please retry"	The service is temporarily unavailable or timed out	Retry with `Retry-After` or exponential backoff, or switch models in the same family. Past 10 minutes, contact us with the `X-Request-ID` header
503 "This conversation is tied to a stateful session that can no longer be resumed…"	The original session is gone	Start a new conversation without `previous_response_id`
The request disconnects mid-flight and is logged as 499	The client disconnected first: a manual cancel, or its read timeout fired (openai-python defaults to 600 seconds)	Use streaming for long outputs and raise the client's read timeout
A stream gets an error event partway (for example "Response stream interrupted, please retry") or drops	The failure came after output started, so the stream cannot resume	Discard the partial output and resend the whole request

Local environment

Symptom	Cause	What to do
"node / npm is not recognized"	Node.js is missing or not on `PATH`	Reinstall from nodejs.org (keep Windows defaults), then reopen the terminal
PowerShell blocks script execution	Windows execution-policy restrictions	Prefer the console's one-click setup command, or run `Set-ExecutionPolicy RemoteSigned` as Administrator

Still stuck after working through these tables? Contact us with the client name, model ID, approximate time, HTTP status code, the X-Request-ID from the response headers, and a screenshot with the key hidden.

Next steps

Error codes and retries: the full status-code table and retry rules
Concurrency, timeouts, and billing: the limits behind 429s and timeouts
FAQ: common questions about addresses, keys, and billing