---
title: "Error Codes and Troubleshooting"
description: "Causes and solutions for 401, 404, 429, 529, 5xx, timeouts, and Claude Code errors when calling 1折AI."
headingIds: {"Troubleshooting Order":"section-1","Error Code Quick Reference":"section-2","Actual Response Samples":"section-3","Troubleshooting by Symptom":"section-4","401 / Invalid token":"section-5","404 / Invalid URL":"section-6","403 / error code: 1010":"section-7","429 Too Many Requests":"section-8","529 / overloaded_error":"section-9","Timeout, streaming disconnects mid-way":"section-10","Claude Code: Goes straight to the login screen":"section-11","Claude Code: Extra inputs are not permitted / context_management returns 400":"section-12","Balance is sufficient but calls fail":"section-13","Limited Retries and Feedback Template":"section-14","Still Not Resolved":"section-15"}
---

<aside className="docs-publication" data-pagefind-ignore>

Documentation maintained by [1ZheAI](https://1zheai.com/en/editorial/#publisher). [Sources and corrections](https://1zheai.com/en/editorial/).

Found an error? [Contact support](mailto:support@1zheai.com) with the page address and a description. Do not send API keys or account credentials.

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

## Troubleshooting Order

1. **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](/en/docs/base-url/).
2. **API key**: Is it complete (no extra spaces or line breaks), has it been deleted, and is it filled into the correct field?
3. **Balance**: Is the balance in the console sufficient?
4. **Model ID**: Is it exactly the same as in [Supported Models](/en/docs/models/)?
5. **Network**: Turn off the proxy and try connecting directly again.
6. **Still not working**: Provide a minimal curl reproduction (see below), and send us the response and timing.

```bash title="最小复现"
curl -i https://1zheai.com/v1/messages \
  -H "x-api-key: sk-你的Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -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 support@1zheai.com |
| 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](https://platform.claude.com/docs/en/api/errors).

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.

<CodeGroup>
```json title="401 API 密钥无效、禁用、过期或额度用完"
{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}
```
```json title="403 账户余额不足"
{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}
```
```json title="403 API 密钥没开通该模型"
{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}
```
```json title="403 IP 不在白名单"
{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}
```
```json title="400 上游参数错误"
{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}
```
```json title="404 路径不存在"
{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}
```
</CodeGroup>

For an explanation of the 404 when the model does not exist or is unavailable, see [Supported Models](/en/docs/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](/en/docs/models/). 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](/en/docs/quickstart-claude-code/) 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):

```bash
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](/en/docs/retries/).

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

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

## Still Not Resolved

Send an email to support@1zheai.com, including the time, model ID, the tool and version you used, and the complete output of `curl -i` (with the API key removed).