> ## 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.

# 错误码速查

> 所有错误码、HTTP 状态与排查建议的速查表

完整的错误结构说明见 [API 错误码](/api-reference/errors)。本页是 **速查表**。

## 4xx 客户端错误

| HTTP | code                        | 排查                         |
| ---- | --------------------------- | -------------------------- |
| 400  | `invalid_request_error`     | 检查请求体 JSON 格式、必填字段         |
| 400  | `invalid_model`             | 模型 ID 拼写或令牌白名单             |
| 400  | `context_length_exceeded`   | 缩短输入 / 切换大上下文模型            |
| 400  | `unsupported_modality`      | 模型不支持图片 / 音频输入             |
| 400  | `invalid_parameter`         | 某个字段值越界(如 temperature > 2) |
| 401  | `invalid_api_key`           | 密钥不存在 / 格式错误 / 包含换行        |
| 401  | `expired_api_key`           | 令牌已过期,延长或新建                |
| 401  | `disabled_api_key`          | 令牌被禁用,启用或新建                |
| 403  | `insufficient_quota`        | 账户或令牌额度耗尽,充值               |
| 403  | `model_not_allowed`         | 编辑令牌增加该模型                  |
| 403  | `ip_not_allowed`            | 来源 IP 不在白名单                |
| 404  | `model_not_found`           | 模型已下线或拼写错误                 |
| 404  | `resource_not_found`        | 任务 / 文件不存在                 |
| 413  | `request_too_large`         | 请求体超过 32MB 上限              |
| 422  | `validation_error`          | Schema 验证失败                |
| 429  | `rate_limit_exceeded`       | 触发 RPM / TPM,退避重试          |
| 429  | `concurrent_limit_exceeded` | 超过并发上限                     |
| 429  | `upstream_rate_limited`     | 上游 429,客户端也应退避             |

## 5xx 服务端错误

| HTTP | code                   | 排查                             |
| ---- | ---------------------- | ------------------------------ |
| 500  | `server_error`         | 网关内部错误,通常自动重试。复现请提交 Request ID |
| 502  | `bad_gateway`          | 上游返回非法响应                       |
| 503  | `upstream_unavailable` | 全部上游通道暂不可用,等待或切换模型             |
| 504  | `upstream_timeout`     | 上游超时,可减短输入或重试                  |

## 任务接口专属

| code              | 适用                       | 说明                        |
| ----------------- | ------------------------ | ------------------------- |
| `task_failed`     | Midjourney / Suno / Sora | 任务上游失败,看 `failure_reason` |
| `task_not_found`  | 异步任务                     | 任务 ID 不存在或已超过保留期          |
| `task_queue_full` | 异步任务                     | 上游队列满,稍后重试                |

## 流式响应中的错误

流式 200 响应中途出错时,以 SSE 形式发送:

```
data: {"error":{"message":"...","type":"server_error","code":"upstream_timeout"}}
data: [DONE]
```

请务必在 SSE 消费时检查 `error` 字段。

## 通用排查流程

<Steps>
  <Step title="复制 Request ID">
    从响应头 `X-OpenPAI-Request-Id` 中拿到 ID。
  </Step>

  <Step title="查日志">
    控制台 → **日志** → 搜索 Request ID,查看模型、Token 用量、错误码。
  </Step>

  <Step title="验证密钥">
    `curl https://openp.ai/v1/models -H "Authorization: Bearer sk-..."` 验证密钥可用。
  </Step>

  <Step title="保留信息">
    仍无法定位时,记录 Request ID、报错时间、复现步骤,以便后续排查。
  </Step>
</Steps>