错误码 | OminiApi 文档

错误响应格式

错误响应的格式取决于你调用的接口，与各家官方格式保持一致：

{
  "error": {
    "message": "insufficient quota",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  },
  "request_id": "7d3f0c9e-..."
}

两个例外

密钥和账号校验失败（Key 无效、停用、过期、IP 不允许、邮箱未验证等）在进入具体接口之前就会被拦截，返回的是 {"success": false, "message": "..."}，不是上面的官方格式，也不带请求 ID。
网关繁忙、请求体过于复杂等情况返回 {"error": {"message": "..."}}。

常见错误

鉴权与账号（401 / 403）

HTTP	message	原因与处理
401	`invalid token`	Key 不存在、格式错误、已撤销或已轮换。检查 Key 是否完整（`sk-` 开头，47 位）
401	`token disabled`	Key 被停用，到「API 密钥」重新启用
401	`token expired`	Key 已过期，新建密钥或修改到期时间
401	`token exhausted`	Key 的「总额度」已用完，调高额度或新建密钥
403	`ip not allowed`	请求来源 IP 不在 Key 的 IP 白名单里
403	`请先完成邮箱验证后再使用此功能`	邮箱未验证，见验证邮箱
403	`请先阅读并接受最新法律文档`	登录控制台，确认新版政策后即可恢复
403	`model not allowed for this key`	模型不在 Key 的「模型白名单」里
403	`model not allowed by organization policy`	组织或团队访问策略不允许该模型，联系组织管理员
400	`client profile not allowed`	平台或组织限制了可用客户端，当前客户端不在允许范围内

余额与限额（402 / 429）

HTTP	message	原因与处理
402	`insufficient quota`	余额或套餐额度不足。充值，或检查 Key 的「扣费偏好」是否只允许用套餐
429	`too many concurrent sessions`	超过 Key 的「并发会话数」
429	`window quota exceeded: ...`	Key 或套餐的 5 小时 / 每日 / 每周 / 每月额度用完，等待窗口重置或重置日额度
429	`plan request limit exceeded`	超过套餐、用户、团队或组织的请求频率 / 并发限制
429	`provider group RPM limit exceeded: 分组名`	该分组当前请求过多，稍后重试或换分组
429	`request rate limited`	上游限流，稍后重试

请求问题（400 / 404 / 408 / 413）

HTTP	message	原因与处理
400	`model is required`	请求里没有 `model`
400	`invalid JSON request body`	请求体不是合法 JSON
400	`model is not supported`	模型名写错，或当前分组没有这个模型。到模型广场核对
400	`No eligible upstream supports the requested interface or model`	这个模型不能通过当前接口调用，换用模型的原生接口，见跨格式调用
400	`unsupported request semantics: ...`	某个参数在目标格式里不支持，去掉该参数
400	`model price not found: 模型名`	该模型暂未定价，暂时无法调用
400	`request blocked by content policy; request ID: ...`	请求内容触发了内容安全策略
400	`JSON request is too complex`	JSON 嵌套过深或节点过多
404	—	接口路径不存在或不支持，见支持的接口
408	`request body read timeout`	请求体 30 秒内没有发送完
413	`request body too large`	请求体超过 16 MiB

服务端问题（5xx）

HTTP	message	原因与处理
503	`upstream request failed`	所有可用线路都失败了。稍后重试，或查看服务状态
503	`relay capacity exhausted`	网关瞬时繁忙，1 秒后重试
504	`upstream request failed`	上游响应超时，建议改用流式请求

为什么 5xx 都是 upstream request failed

出于安全考虑，所有 5xx 错误对外统一显示为 upstream request failed，不透传上游的原始错误信息。具体原因可以在使用日志的请求详情里看到错误类别，或者带上请求 ID 提交工单。

流式中断

流式响应已经开始输出后，如果上游中断，不会再改变 HTTP 状态码，而是在流里发送一个错误事件，message 为 upstream stream interrupted before completion，type 为 upstream_interrupted：

OpenAI 格式：随后发送 data: [DONE]；
Responses 格式：以 response.failed 事件发送。

客户端应当检查流是否正常结束，不完整时重试。

建议的重试策略

状态码	是否重试
400 / 401 / 402 / 403 / 404 / 413	不要重试，先修正请求或账号状态
429	等待后重试，窗口额度类错误需要等窗口重置
408 / 5xx / 流式中断	可以指数退避重试

错误响应格式Copy Anchor Link

常见错误Copy Anchor Link

鉴权与账号（401 / 403）Copy Anchor Link

余额与限额（402 / 429）Copy Anchor Link

请求问题（400 / 404 / 408 / 413）Copy Anchor Link

服务端问题（5xx）Copy Anchor Link

流式中断Copy Anchor Link

建议的重试策略Copy Anchor Link

本页目录