错误处理

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

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

{"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 白名单，调用来源不在其中。不产生费用。	从白名单中的地址调用，或在控制台修改 Key 的白名单。
403	`model_not_allowed`	该 API Key 仅限调用其他模型。不会扣费。	改用该 Key 允许的模型，或在控制台修改 Key 的模型限制。
401	`management_key_required`	向管理 API 发送了 API Key。	改用管理密钥。
403	`activation_required`	创建 Key 时工作空间尚未通过开通就绪检查。	到总览检查服务状态，完成开通后再创建。
403	`insufficient_scope`	`read` 管理密钥尝试写操作。	改用 `write` 管理密钥。
400	`invalid_tags`	标签不符合标签规则：超过 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`	本周期的成员预算已用尽，它覆盖你名下全部 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 本分钟的调用次数已用完。不产生费用。	等待 `Retry-After` 给出的秒数后重试。
429	`concurrency_limited`	工作空间、成员或 Key 同时进行的调用已达上限。不产生费用。	等已有调用结束后重试（`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`	图片调用超时、连接中断、遇到服务方服务器错误，或返回无法核验。	转入核对；仅当确实生成了图片时扣费。
502、504	`video_submit_held`	提交视频任务时无法确认任务：超时、连接中断或遇到服务方服务器错误。	转入核对；仅当确实生成了视频时扣费。
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

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":
        ...

V1 文档

快速开始

用户手册

概览

LLM

图片

视频

通用

错误码

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

重试建议

​错误码

​模型服务方错误（upstream_*）

​重试建议

错误码

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

重试建议