> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误码

> OpenPAI 返回的 HTTP 状态、错误结构与处理建议

OpenPAI 在错误时返回标准 HTTP 状态码 + JSON 错误体。
错误结构与 OpenAI 官方完全兼容,可以无缝接入现有 SDK 的错误处理。

## 错误响应结构

```json theme={null}
{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
```

| 字段        | 含义                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------- |
| `message` | 人类可读的错误描述,可直接展示给开发者                                                                                           |
| `type`    | 错误类别:`invalid_request_error` / `authentication_error` / `billing_error` / `rate_limit_error` / `server_error` |
| `param`   | 出错的字段名(若适用)                                                                                                   |
| `code`    | 机器可识别的错误码                                                                                                     |

## 常见错误码

### 400 invalid\_request

| code                      | 说明                      |
| ------------------------- | ----------------------- |
| `invalid_request_error`   | 请求体格式错误 / 缺少必填字段        |
| `invalid_model`           | 模型 ID 不存在或不在令牌白名单       |
| `context_length_exceeded` | 输入 + 输出 token 超过模型上下文窗口 |
| `unsupported_modality`    | 该模型不支持图片 / 音频 / 视频输入    |

### 401 authentication

| code               | 说明                       |
| ------------------ | ------------------------ |
| `invalid_api_key`  | API Key 不存在 / 已删除 / 格式错误 |
| `expired_api_key`  | 令牌已过期                    |
| `disabled_api_key` | 令牌已被禁用                   |

### 403 forbidden

| code                 | 说明          |
| -------------------- | ----------- |
| `insufficient_quota` | 账户或令牌额度耗尽   |
| `ip_not_allowed`     | 来源 IP 不在白名单 |
| `model_not_allowed`  | 该令牌没有此模型权限  |

### 404 not\_found

| code                 | 说明                |
| -------------------- | ----------------- |
| `model_not_found`    | 模型不存在(已下线 / 拼写错误) |
| `resource_not_found` | 资源(任务、文件)不存在      |

### 429 rate\_limit

| code                        | 说明              |
| --------------------------- | --------------- |
| `rate_limit_exceeded`       | 触发 RPM / TPM 限流 |
| `concurrent_limit_exceeded` | 并发数超过分组上限       |
| `upstream_rate_limited`     | 上游厂商返回 429      |

429 响应头中包含 `Retry-After`(秒),建议使用指数退避重试。

### 5xx server\_error

| code                   | 说明            |
| ---------------------- | ------------- |
| `server_error`         | 网关内部错误,通常自动重试 |
| `upstream_unavailable` | 全部上游通道均不可用    |
| `upstream_timeout`     | 上游超时          |
| `bad_gateway`          | 上游返回非法响应      |

5xx 错误**不会扣费**(若上游已生成 token,会按实际用量结算)。

## 流式响应中的错误

流式响应中如果中途出错,会以 SSE 形式发送一个错误事件后关闭连接:

```
data: {"error":{"message":"Upstream timeout","type":"server_error","code":"upstream_timeout"}}

data: [DONE]
```

客户端应监听 SSE 数据中的 `error` 字段,而不仅是 HTTP 状态码。

## 重试建议

```python theme={null}
from openai import OpenAI
import time

client = OpenAI(api_key="sk-...", base_url="https://openp.ai/v1")

def call_with_retry(**kwargs):
    delay = 1
    for attempt in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except openai.RateLimitError:
            time.sleep(delay)
            delay = min(delay * 2, 30)
        except openai.APIError as e:
            if e.status_code >= 500:
                time.sleep(delay)
                delay = min(delay * 2, 30)
            else:
                raise
    raise RuntimeError("max retries exceeded")
```

## 报告问题

收到无法理解的错误时:

1. 复制响应头中的 `X-OpenPAI-Request-Id`。
2. 在控制台 → 日志中搜索该 ID,查看模型、Token 用量、错误码等元数据。
3. 仍不能定位,记录 Request ID 与复现步骤,等待后续问题排查。