# 错误 (/docs/zh-CN/errors)

每条错误信息都写明了下一步该做什么，你可以直接展示给能处理它的人，代码则按 HTTP 状态码分支处理。每个响应（包括错误响应）都带有 `X-Request-ID`，联系客服时请附上它。

## 状态码 [#状态码]

| 状态码 | `code` | 处理方法 |
|---|---|---|
| 400 | `invalid_request`、`invalid_parameter`、`missing_required_parameter`、`unsupported_parameter`、`unsupported_content`、`unsupported_endpoint`、`context_length_exceeded`、`content_policy_violation` | 按错误信息修正或去掉其中指出的参数、内容或端点，然后重新发送。 |
| 401 | `invalid_api_key`、`api_key_expired`、`api_key_disabled` | 到 [API Key](https://www.ohmygpt.com/keys) 页面换一个有效的 Key。 |
| 402 | `insufficient_credits`、`api_key_spend_limit_exceeded` | 到[账单](https://www.ohmygpt.com/billing)页面充值，或调高这个 Key 的消费额度。 |
| 403 | `model_not_allowed`、`provider_not_allowed`、`permission_denied`、`account_suspended` | 到 [API Key](https://www.ohmygpt.com/keys) 页面修改错误信息指出的设置（可调用的模型、可使用的供应商或管理员 Key），或联系客服。 |
| 404 | `model_not_found`、`not_found` | 从 `GET /v1/models` 复制模型 ID，或检查错误信息指出的 ID 或 URL。 |
| 409 | `conflict` | 上一个响应，或带同一个 `Idempotency-Key` 的请求还在进行中。等它结束后再发送。 |
| 413 | `request_too_large` | 减小请求体。 |
| 415 | `invalid_request` | 以 JSON 发送请求体，并带上 `Content-Type: application/json`。 |
| 429 | `rate_limit_exceeded` | 等待 `Retry-After` 秒后重新发送。 |
| 500、502、503、504 | `model_error`、`model_overloaded`、`model_unavailable`、`model_timeout`、`service_unavailable`、`internal_error` | 退避重试，或换一个模型。 |

参数错误会保留模型自己的原话，所以错误信息里能看到可接受的取值范围：

```json
{
  "error": {
    "param": null,
    "code": "invalid_request",
    "message": "Invalid 'temperature': decimal above maximum value. Expected a value <= 2, but got 5 instead.",
    "type": "invalid_request_error"
  }
}
```

## URL 错误 [#url-错误]

404 的错误信息里写的是你的请求路径而不是模型时，说明 URL 不对：

```json
{"message":"Cannot POST /v1/v1/chat/completions","error":"Not Found","statusCode":404}
```

最常见的原因是 base URL 写错了。OpenAI SDK 填 `https://api.ohmygpt.com/v1`；Anthropic SDK、Claude Code 和 Gemini SDK 填 `https://api.ohmygpt.com`，它们会自己加上 `/v1`。见[各 SDK 的 base URL](/docs/zh-CN/api#对话协议)。

## 错误响应体 [#错误响应体]

响应体的格式跟随你调用的端点所属的协议，所以你的 SDK 会抛出它惯常的异常类型。

```json tab="Chat Completions, Responses"
{
  "error": {
    "param": "model",
    "code": "model_not_found",
    "message": "The model `no/such-model` does not exist. List available models with `GET /v1/models`.",
    "type": "not_found_error"
  }
}
```

```json tab="Anthropic Messages"
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key. Create or manage your keys at https://www.ohmygpt.com/keys."
  }
}
```

```json tab="Gemini"
{
  "error": {
    "code": 401,
    "message": "Invalid API key. Create or manage your keys at https://www.ohmygpt.com/keys.",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_API_KEY",
        "domain": "ohmygpt.com"
      }
    ]
  }
}
```

OpenAI 格式按 `code` 分支。Anthropic 格式在 `error.type` 里给出状态类别，Gemini 格式则在 `details[].reason` 里给出大写的错误码。

以 OpenAI Python SDK 为例：

```python
import os

import openai
from openai import OpenAI

client = OpenAI(base_url="https://api.ohmygpt.com/v1", api_key=os.environ["OHMYGPT_API_KEY"])

try:
    completion = client.chat.completions.create(
        model="no/such-model",
        messages=[{"role": "user", "content": "Hi"}],
    )
except openai.RateLimitError as e:          # 429
    retry_after = int(e.response.headers.get("retry-after", "1"))
except openai.APIStatusError as e:          # any other non-2xx
    print(e.status_code, e.code, e.response.headers.get("x-request-id"))
```

```text
404 model_not_found 01a19b5f-6ab6-7dc0-88ff-f5c95e0169e4
```

## 流式输出中途出错 [#流式输出中途出错]

流一旦开始，状态码就已经是 200。如果生成中途停止，流会以一个错误事件结束，取代正常的最后一个事件：

```text tab="Chat Completions"
data: {"error":{"param":null,"code":"model_error","message":"The model `zhipu/glm-5.3-flash` stopped mid-response, so the output is incomplete. Try again.","type":"server_error"}}
```

```text tab="Responses"
event: response.failed
data: {"type":"response.failed","response":{"status":"failed","error":{"code":"model_error","message":"..."}, ...}}
```

```text tab="Anthropic Messages"
event: error
data: {"type":"error","error":{"type":"api_error","message":"..."}}
```

OpenAI 和 Anthropic 的 SDK 会在你遍历流时把它作为异常抛出，按处理其他错误的方式处理即可。如果你自己解析流，凡是没有以最后一个事件（`data: [DONE]`、`message_stop` 或 `response.completed`）结束的流，都应视为不完整。

## 何时重试 [#何时重试]

供应商在应答前失败时，OhMyGPT 已经会把请求转给另一家，这部分不需要你写重试逻辑。你的代码只需这样处理：

- **400、401、402、403、404：** 先修改请求、Key 或余额；原样重发只会得到同样的结果。
- **429：** 等待 `Retry-After` 秒后重新发送。
- **500、502、503、504：** 按指数退避重试几次，响应带有 `Retry-After` 头时按它等待。如果仍然出错，换一个模型。