Error Codes and Troubleshooting

Causes and solutions for 401, 404, 429, 529, 5xx, timeouts, and Claude Code errors when calling 1折AI.

Go through the checklist below in order; most issues can be found within the first three steps.

Troubleshooting Order

Address: For Anthropic-family tools, fill in https://1zheai.com; for OpenAI-family tools, fill in https://1zheai.com/v1. See Base URL and Authentication.
API key: Is it complete (no extra spaces or line breaks), has it been deleted, and is it filled into the correct field?
Balance: Is the balance in the console sufficient?
Model ID: Is it exactly the same as in Supported Models?
Network: Turn off the proxy and try connecting directly again.
Still not working: Provide a minimal curl reproduction (see below), and send us the response and timing.

1
curl -i https://1zheai.com/v1/messages \
2
  -H "x-api-key: sk-你的Key" \
3
  -H "anthropic-version: 2023-06-01" \
4
  -H "content-type: application/json" \
5
  -d '{"model":"claude-sonnet-5-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

-i will print the status code and response headers together, which is very useful for troubleshooting.

Error Code Quick Reference

Status Code	Common Cause	What to Do
400	Problem with the request body: wrong parameter name, wrong field type, `max_tokens` exceeds the model limit, or includes a beta field the upstream does not recognize	Check the field indicated in `message`; for Claude Code, see “Extra inputs are not permitted” below
401	API key is invalid, deleted, disabled, expired, its own quota is exhausted, or it is missing or placed in the wrong header	The response is always `Invalid token`; check each item; for Anthropic native, use `x-api-key` or `Authorization: Bearer`
403	Insufficient account balance (`billing_error` / `insufficient_quota`); this API key has not enabled that model; the request IP is not in this API key’s whitelist (both are `permission_error`)	Top up, or edit this API key’s model restrictions and IP whitelist on the “API Keys” page
404	Wrong path, or the model does not exist / is currently unavailable	`Invalid URL` verify the address; `not_found_error` / `model_not_found` verify the model ID and available list
413	Request body too large	Reduce the content sent at once; split large files into segments
429	Temporary upstream rate limiting. We currently do not set rate limits on API keys	Retry later; add exponential backoff for batch jobs
503	The model exists but there is temporarily no healthy upstream service, or a temporary service failure	Retry later; if it persists, provide the request ID and contact support
500 / 502	Temporary gateway or upstream failure	Retry later; if it persists, send an email to [email protected]
504	Request timed out	Use streaming for long outputs; increase the client timeout
529	Upstream Anthropic overloaded (`overloaded_error`)	Wait a few seconds and retry, or temporarily switch to another model

For the full meaning of Anthropic’s official error types (invalid_request_error, authentication_error, rate_limit_error, overloaded_error, etc.), see the official Errors documentation.

Errors returned by the upstream are passed through with the status code and message unchanged, and message appends this request’s request id at the end. When going through /v1/messages, the outer layer is the official {"type":"error","error":{...}} structure, and error.type is filled with the official type based on the status code; when going through /v1/chat/completions, it is OpenAI’s {"error":{...}} structure.

Actual Response Samples

Below are the actual responses tested against /v1/messages on 2026-10-15. When going through /v1/chat/completions, the content is the same, the outer layer has no "type":"error", and error has an additional code field.

{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}

{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}

{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}

{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}

{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}

{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}

For an explanation of the 404 when the model does not exist or is unavailable, see Supported Models. The request id in the response corresponds to your specific request; include it when reporting an issue.

Troubleshooting by Symptom

401 / Invalid token

The API key had extra spaces or line breaks when copied; copy it again.
The API key has been deleted or disabled in the console, or has expired, or its own quota is exhausted. In all these cases, the response is the same message Invalid token.
In Claude Code, both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are set, and one of them is an old value: keep only one, ANTHROPIC_AUTH_TOKEN is recommended.
The env of settings.json overrides the same-named variable exported in the terminal; if changing the terminal variable has no effect, check ~/.claude/settings.json.

404 / Invalid URL

First look at the error type: not_found_error or model_not_found requires checking the Model ID and Available List. For Invalid URL, check /v1: OpenAI SDK, Cursor, Cline (OpenAI Compatible) should be filled up to https://1zheai.com/v1; Claude Code and Anthropic SDK should only fill in https://1zheai.com; filling in /v1 will result in /v1/v1/messages.

403 / error code: 1010

If the response contains only the line error code: 1010 and no JSON, the request was blocked before reaching the gateway. It is currently known that sending requests directly with Python’s standard library urllib will encounter this (its default User-Agent is Python-urllib/3.x). Add your own User-Agent in the request headers, or switch to the official SDK, requests, httpx.

429 Too Many Requests

We currently do not set rate limits on API keys. Receiving a 429 usually means high upstream load; just retry later. For batch jobs, it is recommended to add exponential backoff: wait a period after a failure before retrying, double the wait time each time, and control concurrency yourself with a queue.

529 / overloaded_error

Upstream Anthropic is temporarily overloaded; this is unrelated to your API key or balance. Wait a few seconds and retry; if you are in a hurry, temporarily switch to another model in the same series.

Timeout, streaming disconnects mid-way

For long responses, use streaming ("stream": true) as much as possible; it is less likely to be cut off by intermediate network devices.
Claude Code can use API_TIMEOUT_MS to increase the timeout; the default is 600000 (10 minutes).
If a proxy is on, turn it off and try once first; many disconnects come from proxy nodes.

Claude Code: Goes straight to the login screen

This means Claude Code did not read your API key. Run /status in Claude Code and look at the base URL and credential source lines; if they are empty, go back to Claude Code Integration to check environment variables or settings.json.

Claude Code: Extra inputs are not permitted / context_management returns 400

Claude Code includes some experimental beta fields in requests; strict upstreams that do not recognize them will return 400. Set the following environment variables to turn them off (from Claude Code’s official LLM gateway documentation):

1
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

Balance is sufficient but calls fail

If only a specific model fails, that model may be temporarily unavailable, the ID may be written incorrectly, or this API key has model restrictions set (403 This token has no access to model …).
If all fail and it is 401, check whether this API key has a quota limit set and it has been exhausted, or it has expired. You can see this in the “Quota ($)” and “Expires” columns on the “API Keys” page.
For other cases, see the error code table above.

Limited Retries and Feedback Template

Do not use infinite loops to mask configuration errors. For SDK timeouts, automatic retry counts, and backoff handling, see Timeouts and Retries.

When contacting support, you can copy the template below, delete the key, authentication headers, and private content before sending:

1
发生时间与时区：
2
客户端及版本：
3
请求方法与完整路径：
4
模型 ID：
5
HTTP 状态码：
6
request id（如有）：
7
脱敏后的错误正文：
8
最小请求能否复现：
9
是否使用代理 / 是否仅某个模型失败：

Still Not Resolved

Send an email to [email protected], including the time, model ID, the tool and version you used, and the complete output of curl -i (with the API key removed).