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

# 错误处理

> 错误结构，以及 /v1 API 返回的全部错误码。

所有错误使用同一结构，兼容 OpenAI SDK 的错误处理。请根据 `error.code` 分支处理，不要依赖 HTTP 状态码或文案。

```json theme={null}
{
  "error": {
    "code": "model_unavailable",
    "message": "The model does not exist or is disabled.",
    "type": "not_found_error"
  },
  "request_id": "2f6c1d0e9a"
}
```

| 字段 | 含义 |
| - | - |
| `error.code` | 下表中的稳定错误码，是唯一应依赖的判断依据。 |
| `error.message` | 简短英文说明，用于日志和 SDK 异常；措辞可能调整，不包含模型服务方原始错误文本。 |
| `error.type` | 按 HTTP 状态划分的错误类别：`invalid_request_error`（400、413）、`authentication_error`（401）、`insufficient_quota`（402）、`permission_error`（403）、`not_found_error`（404）、`conflict_error`（409）、`rate_limit_error`（429）、`service_unavailable`（503）或 `api_error`（其他 5xx）。 |
| `error.param` | 可选。参数错误时为被拒绝的字段名。 |

对话补全、Responses 和 Embeddings 的错误会带上 `request_id`，同时通过 `X-Request-ID` 响应头返回。请保存它：支持人员凭它定位单次调用。控制台**用量日志**始终显示汇总和图表；客户账户默认不显示逐条请求列表，需要核查某次调用时，请把请求 ID 发给 [support@omnirelay.ai](mailto:support@omnirelay.ai)。

请求参数错误会在可定位时返回 `error.param`，例如 `temperature` 或 `reasoning.effort`；此字段只包含参数名，不包含参数值。请同时核对模型能力与推理强度组合限制。Responses 返回原生参数名。平台预算／协议校验发生在发送前；模型服务方以 HTTP 400 或 422 拒绝请求时释放预留、不收费；能识别的错误码和安全字段路径会返回，否则返回 `invalid_parameter`。部分模型会忽略不支持的字段而不报错，这类调用正常成功，不返回 `error.param`。

```json theme={null}
{"error":{"code":"unsupported_parameter","message":"This model does not support one of the request parameters. Nothing was charged.","type":"invalid_request_error","param":"temperature"},"request_id":"your-request-id"}
```

流式响应在 HTTP 200 之后失败时，会在最后一个 `data:` 事件中返回同样的 `error` 对象（对话补全），或返回带 `code` 和 `message` 的 `error` 事件（Responses），且不会以 `[DONE]` 结束。

## 错误码

| 状态 | 错误码 | 含义 | 处理方式 |
| - | - | - | - |
| 400 | `invalid_json` | 请求体不是合法 JSON。 | 修正请求体。 |
| 400 | `invalid_input` | 字段缺失、为空、过长或类型错误。 | 检查 `model` 与 `messages`。 |
| 400 | `unsupported_parameter` | 所选模型不支持此字段或能力。不收费。 | 核对模型规则，移除字段。 |
| 400 | `invalid_parameter` | 真实字段值、输出上限或消息不合法。不收费。 | 核对限制及参数值。 |
| 400 | `context_length_exceeded` | 输入加输出上限超出模型上下文长度。不收费。 | 缩短输入或降低输出上限。 |
| 400 | `stream_usage_not_supported` | 该模型不支持带用量统计的流式响应。不收费。 | 改为非流式请求。 |
| 400 | `unsupported_protocol` | 该模型不能通过此接口调用。不收费。 | 改用模型支持的接口。 |
| 403 | `ip_not_allowed` | 该 API Key 设置了 [IP 白名单](https://omnirelay.ai/docs/cn/overview/rate-limits.md)，调用来源不在其中。不产生费用。 | 从白名单中的地址调用，或在控制台修改 Key 的白名单。 |
| 403 | `model_not_allowed` | 该 API Key [仅限调用其他模型](https://omnirelay.ai/docs/cn/overview/authentication.md#限定-key-可调用的模型)。不会扣费。 | 改用该 Key 允许的模型，或在控制台修改 Key 的模型限制。 |
| 401 | `management_key_required` | 向 [管理 API](https://omnirelay.ai/docs/cn/general/management-api.md) 发送了 API Key。 | 改用管理密钥。 |
| 403 | `activation_required` | 创建 Key 时工作空间尚未通过开通就绪检查。 | 到总览检查服务状态，完成开通后再创建。 |
| 403 | `insufficient_scope` | `read` 管理密钥尝试写操作。 | 改用 `write` 管理密钥。 |
| 400 | `invalid_tags` | 标签不符合[标签规则](https://omnirelay.ai/docs/cn/general/tags.md#规则)：超过 10 个、key 重复、含不允许的字符，或 key、value 过长。 | 修正 `X-OmniRelay-Tags` 请求头、`tags` 字段或 Key 的默认标签。 |
| 401 | `unauthorized` | API Key 缺失、不存在或已撤销，或账户已停用。 | 重新创建 API Key。 |
| 401 | `request_no_longer_authorized` | 调用开始时 Key 或权限发生变化，请求未发送、未收费。 | 检查 Key 后重试。 |
| 402 | `insufficient_balance` | 余额不足以支付本次请求。 | 在控制台充值。 |
| 402 | `inference_budget_or_access_denied` | 真实请求在派发前未通过原子的费用预留或访问校验。不收费。 | 检查账户可用余额、已预留金额、Key 剩余预算和模型权限。即使提示词很短，余额和预算也需覆盖最高预留；均正常时联系支持确认工作空间和平台额度。 |
| 402 | `key_budget_exceeded` | API Key 预算已用尽。不收费。 | 提高预算或更换 API Key。 |
| 402 | `member_budget_exceeded` | 本周期的[成员预算](https://omnirelay.ai/docs/cn/general/usage-billing.md#成员预算)已用尽，它覆盖你名下全部 API Key 和模型体验。不会扣费。 | 请管理员提高预算，或等待下一个周期。 |
| 404 | `model_unavailable` | 模型不存在或已停用。 | 调用 `GET /v1/models`。 |
| 404 | `not_found` | 未知的 `/v1` 路由。 | 检查路径与方法。 |
| 409 | `request_conflict` | 相同请求 ID 的调用正在处理中。 | 不要重发，等待前一次调用完成。 |
| 413 | `payload_too_large` | 请求体超过 4 MiB。 | 缩短对话或减少附带内容。 |
| 429 | `rate_limited` | 工作空间、成员或 Key 本分钟的[调用次数](https://omnirelay.ai/docs/cn/overview/rate-limits.md)已用完。不产生费用。 | 等待 `Retry-After` 给出的秒数后重试。 |
| 429 | `concurrency_limited` | 工作空间、成员或 Key 同时进行的[调用](https://omnirelay.ai/docs/cn/overview/rate-limits.md)已达上限。不产生费用。 | 等已有调用结束后重试（`Retry-After: 1`）。 |
| 429 | `upstream_rate_limited` | 模型服务方在处理前因你账户的速率上限拒绝了此调用，预扣已释放，不产生费用。 | 稍后重试（`Retry-After: 1`）。 |
| 503 | `channel_unavailable` | 该模型暂时不可用。不收费。 | 稍后重试或更换模型。 |
| 503 | `live_provider_not_configured` | 所选模型为真实模型，而真实推理尚未启用。 | 检查真实服务开通状态并联系支持。 |
| 503 | — | 工作空间开通、轮换或凭据核验尚未完成；调用未发往模型服务方。 | 等待启用，或携请求 ID 联系支持。 |
| 503 | `runtime_maintenance` | 维护期间暂停新真实调用；调用未发往模型服务方。 | 等几分钟后重试。 |
| 503 | `storage_unavailable` | 存储暂时不可用，请求可能已发送。 | 重发前携请求 ID 联系支持。 |

## 模型服务方错误（`upstream_*`）

这些错误码表示调用已到达模型服务方，并在服务方侧出错。是否收费取决于模型输出是否已经送达你：

* **尚未送达任何输出**：预留立即释放，不收费。非流式调用、以及在首个输出前失败的流式调用都属于这种情况。
* **已送达部分输出**（流式中途断开），或**模型服务方的回答已到达但无法核验**：调用转入人工核对，按模型服务方用量记录结算。不要自动重发；预留长时间未释放时，携请求 ID 联系支持。

| 状态 | 错误码 | 含义 | 是否收费 |
| - | - | - | - |
| 502 | `upstream_rejected` | 模型服务方拒绝了调用（400、422、429 以外的非 2xx 回复）。 | 否。 |
| 502 | `upstream_transport_error` | 与模型服务方的连接失败。 | 否，除非已送达输出。 |
| 502 | `upstream_stream_incomplete` | 模型服务方的流式响应在回答完成前结束。 | 否，除非已送达输出。 |
| 502 | `upstream_stream_error` | 模型服务方的流式响应报告错误。 | 否，除非已送达输出。 |
| 504 | `upstream_timeout` | 模型服务方未能及时响应。 | 否，除非已送达输出。 |
| 499 | `upstream_cancelled` | 客户端在完成前取消了调用。 | 否，除非已送达输出。 |
| 502 | `upstream_invalid_response` | 模型服务方的回答已到达但未通过校验（也可能报告为 `upstream_invalid_json`、`upstream_invalid_content_type`、`upstream_model_mismatch`、`upstream_unsupported_delta`、`upstream_premature_usage`、`upstream_duplicate_usage`、`upstream_response_too_large` 或 `upstream_body_too_large`）。 | 转入核对。 |
| 502 | `upstream_invalid_tool_call` | 模型服务方返回的工具调用与声明的工具不符。 | 转入核对。 |
| 502 | `upstream_invalid_structured_output` | 模型服务方的结构化输出不符合请求的 schema。 | 转入核对。 |
| 502 | `usage_missing`、`usage_invalid`、`usage_unsupported` | 回答已到达，但缺少可计费的有效用量。 | 转入核对。 |
| 502 | `cost_exceeds_hold` | 回答费用超过了预留金额。 | 转入核对，不自动扣费。 |
| 502、504 | `image_call_held` | [图片调用](https://omnirelay.ai/docs/cn/images/image-generation.md#失败与扣费)超时、连接中断、遇到服务方服务器错误，或返回无法核验。 | 转入核对；仅当确实生成了图片时扣费。 |
| 502、504 | `video_submit_held` | 提交[视频任务](https://omnirelay.ai/docs/cn/videos/video-generation.md#失败与扣费)时无法确认任务：超时、连接中断或遇到服务方服务器错误。 | 转入核对；仅当确实生成了视频时扣费。 |
| 503 | `settlement_conflict` | 调用已完成但未能入账。 | 转入核对。 |

`upstream_rate_limited`（429）见上表：它是处理前的拒绝，从不收费。

耗时超过约 25 秒的图片调用会在完成前先返回 `200`，因此上述错误也可能作为 `200` 响应的 JSON 正文返回，请先检查解析后的正文中是否有 `error`。

## 重试建议

真实推理不能仅凭 HTTP 状态判断是否收费，请关闭 SDK 自动重试，并按 `error.code` 决定：

* 标明**不收费**的错误码（全部 4xx 拒绝、`upstream_rejected`、`channel_unavailable`、`runtime_maintenance`）可以重试；`rate_limited`、`concurrency_limited` 和 `upstream_rate_limited` 请退避后重试。
* `upstream_transport_error`、`upstream_timeout` 和流式相关错误码，对非流式调用或尚未送达输出的流式调用不收费，可以重试。
* **转入核对**的错误码，或已送达部分输出后断开的流式调用，不要自动重发；需要确认结果时，检查余额并携请求 ID 联系支持。

```python Python theme={null}
from openai import APIStatusError

try:
    client.chat.completions.create(model="gpt-6-luna", messages=messages)
except APIStatusError as error:
    code = error.response.json()["error"]["code"]
    if code == "insufficient_balance":
        ...
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.