错误码
OminiGate 所有接口采用统一的错误响应结构。本页帮助你快速查找错误含义并决定如何处理。
错误码
响应格式
网关、鉴权、管理接口返回的错误都共享同一层 error 封装。任意非 2xx 响应均可解析顶层 error 对象，获得错误分类、稳定 code 以及人类可读的 message。
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API key provided."
}
}字段说明
typestring错误大类。相同大类下的错误往往可以用相同策略处理（如上游错误重试、账单错误提示用户）。
codestring稳定的小写下划线标识。适合写进分支判断逻辑——版本升级不会改 code。
messagestring英文、面向开发者的描述，适合写入日志；若要展示给终端用户请自行做本地化。
paramstring，可选仅当错误由某个具体请求字段触发时才出现（如 model、email），可用来在 UI 上高亮出错输入。
authentication_error
HTTP 401请求未通过鉴权。凭据缺失、格式错误、已过期或不再被系统识别。
invalid_api_key
HTTP 401
Invalid API key provided.
响应示例
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API key provided."
}
}常见原因
- 请求缺少 Authorization 头，或 Value 不符合 Bearer sk-omg-xxx 格式。
- 该 API Key 已在 Dashboard 被删除，或因疑似泄露被自动吊销。
- 把 Dashboard 登录 JWT 错当成 API Key 使用——API Key 必定以 sk-omg- 开头。
- Key 属于另一个环境，或自部署以来已被重新生成。
处理建议
- 再次确认请求头：Authorization: Bearer sk-omg-<your-key>。注意中间的空格和 Bearer 大小写。
- 打开 Dashboard → API Keys 核对 Key 存在且处于启用状态。
- 若 Key 可能泄露，立即删除并重新生成；所有使用该 Key 的环境同步更新。
- 用 curl -v 或 mitmproxy 等抓包工具确认请求头确实被发送出去——某些 CDN 或 SDK 封装会悄悄剥离 Authorization。
expired_api_key
HTTP 401
API key has expired.
响应示例
{
"error": {
"type": "authentication_error",
"code": "expired_api_key",
"message": "API key has expired."
}
}常见原因
- 创建 Key 时设置了过期时间，该时间已到达。
- Key 已完成轮换，但还有部分部署环境持有旧值。
- 历史 Key 在收紧后的保留策略下被批量过期。
处理建议
- 在 Dashboard → API Keys 查看每个 Key 的 expires_at 与状态。
- 生成新的 Key 并同步到所有环境（生产、预发、CI、本地 .env 等）。
- 如果不希望 Key 过期，下次创建时保持 expires_at 为空。
- 在密钥管理系统（AWS Secrets Manager、Vault、Doppler 等）里配置轮换提醒，避免下次被动更换。
invalid_request_error
HTTP 400请求参数校验失败。必填字段缺失、格式错误或超出允许范围。
invalid_request
HTTP 400
Invalid request body.
响应示例
{
"error": {
"type": "invalid_request_error",
"code": "invalid_request",
"message": "Invalid request body."
}
}常见原因
- 请求体不是合法 JSON——常见原因是多余逗号、未转义引号，或缺少 Content-Type: application/json 头。
- JSON 能解析但不符合接口 schema：字段类型错误（如 messages 传成字符串而非数组）、含未知字段、或取值越界（如 temperature > 2）。
- 把非流式请求体发到流式接口或反之——如设了 stream: true 却没按 SSE 读取，或把 Anthropic 格式 messages 发给 /v1/chat/completions。
- multipart/form-data 上传（/v1/images 编辑或视频参考图）缺少必填 part，或字段名不对。
处理建议
- 按 OpenAI chat completions 或 Anthropic messages schema 校验请求体，先用 jq . 过一遍排除语法问题。
- 显式设置 Content-Type: application/json。某些 SDK 在请求体较小或为空时会悄悄丢头。
- 回头对照 docs/ → API Reference 的接口文档，核对每个必填字段及类型。
- 如为流式响应，请按 Server-Sent Events（text/event-stream）逐条消费，不要整体 buffer。
invalid_model
HTTP 400param: model
The model does not exist.
响应示例
{
"error": {
"type": "invalid_request_error",
"code": "invalid_model",
"message": "The model does not exist.",
"param": "model"
}
}常见原因
- model 字段格式错误——缺少厂商前缀（如只传 gpt-4o 而非 openai/gpt-4o）、斜杠方向错误，或带前后空白。
- 传入了展示名或营销名（如 "GPT-4 Omni"），而不是规范的 slug。
- 字段为空、为 null，或是 "default"、"auto" 这类网关不接受的占位值。
- SDK 在发送前改写了 model 名（如自动剥掉了厂商前缀）。
处理建议
- 使用规范的 provider/model slug：openai/gpt-4o、anthropic/claude-sonnet-4-20250514、google/veo-2——统一小写，统一正斜杠。
- 调用 GET /api/v1/models 从响应的 slug 字段直接复制，不要手打模型名。
- 先去掉前后空白，再用 curl -v 或 SDK 的 debug 日志确认实际发出的字符串。
- 如果 SDK 配置了 baseURL 覆写，关闭任何 model 改写中间件，或在每次请求时显式指定 model。
missing_parameter
HTTP 400
A required parameter is missing.
响应示例
{
"error": {
"type": "invalid_request_error",
"code": "missing_parameter",
"message": "A required parameter is missing."
}
}常见原因
- 缺少必填的顶层字段——如 /v1/chat/completions 缺 messages，/v1/images 和 /v1/videos/* 缺 model 或 prompt。
- 嵌套必填字段缺失，如 messages[] 每条的 role 或 content，或 content block 缺 type。
- 视频接口没有提供当前 action 需要的资源——如 POST /v1/videos/{provider}/create 没带 prompt，或 /status 没传 task id。
- 字段存在但值为空串或空数组，网关视为缺失。
处理建议
- 回查接口文档的必填字段清单；错误响应中的 param（如有）就指向缺失字段。
- /v1/chat/completions：必须包含 model 和非空 messages 数组，每条消息都要有 role 和 content。
- /v1/videos/{provider}/{action}：create 时需带 model 和 prompt；status / result 时要带 create 返回的 task id。
- 打印 SDK 最终发出的 JSON（不是序列化前的对象），以防 null 剥离或 schema 校验悄悄丢字段。
video_tier_not_found
HTTP 400param: tier
Requested pricing tier not found for this model.
响应示例
{
"error": {
"type": "invalid_request_error",
"code": "video_tier_not_found",
"message": "Requested pricing tier not found for this model.",
"param": "tier"
}
}常见原因
- 该模型不存在你请求的 tier——如向 google/veo-2 请求 "4k"，但它只提供 720p 和 1080p。
- tier 名拼错或大小写与目录不一致（如 "HD" vs "hd"、"1080P" vs "1080p"）。
- 模型支持多个 tier，但在必填 tier 的模型上省略了该字段。
- 把另一家厂商模型的 tier 名误用到本次请求上（如把 runway 的 tier 名发给 veo）。
处理建议
- 调用 GET /api/v1/models/{slug}，查看 pricing.video.tiers 数组，确认合法的 tier 标识。
- tier 值要与目录中的字符串逐字符一致——区分大小写，与 pricing JSON 中存储的值完全相同。
- 如果不关心 tier，可省略该字段回退到模型默认 tier（前提是模型提供默认值）。
- 切换 tier 后请重新核对每秒价格——不同 tier 费用不同，可能超出你的预算限制。
not_found_error
HTTP 404目标资源不存在或已被删除。
not_found
HTTP 404
Resource not found.
响应示例
{
"error": {
"type": "not_found_error",
"code": "not_found",
"message": "Resource not found."
}
}常见原因
- URL 路径错误——漏了 /v1 前缀，在 OpenAI 兼容路径上用了 Anthropic 路径，或拼写错误如 /v1/chat/completion（少了 s）。
- 用了错误的 base URL 调 Dashboard 接口，或给 API 接口加了 /api/v1 前缀（API Key 走 /v1/*，不走 /api/v1/*）。
- HTTP 方法错误——Ominigate 只使用 GET（读）和 POST（写/动作），PUT/DELETE/PATCH 一律返回 404。
- 路径中的资源 id 不属于当前账号（如想取别人的 API Key 或视频任务）。
处理建议
- 对照接口文档核对 URL：OpenAI 兼容走 /v1/chat/completions，Anthropic 兼容走 /v1/messages，图像走 /v1/images，视频走 /v1/videos/{provider}/{action}。
- 确认 base URL：API 调用（sk-omg- 鉴权）用 https://api.ominigate.ai；Dashboard 接口（JWT 鉴权）走 Dashboard 域名。
- 把所有 PUT/DELETE/PATCH 请求改成 POST，并在路径中显式指定 action。
- 如果路径看起来没问题，请携带响应头 X-Request-Id 联系 support@ominigate.ai。
model_not_found
HTTP 404
Model not found.
响应示例
{
"error": {
"type": "not_found_error",
"code": "model_not_found",
"message": "Model not found."
}
}常见原因
- slug 格式正确，但该模型从未在 Ominigate 上线——请在 /api/v1/models 公开目录确认。
- 模型已从目录中下架，无法再通过网关路由。
- 你的 API Key 配置了模型白名单且不含此模型，网关以 not found 方式反馈（而非 forbidden）。
- 该模型是预览版／Beta，需要账号级别的白名单，当前账号尚未开通。
处理建议
- 调用 GET /api/v1/models，确认该 slug 存在且 status 为 "active"；只有 active 的模型可路由。
- 如果目录里有但仍返回 404，打开 Dashboard → API Keys 移除这把 Key 的模型白名单限制。
- 若模型已下架，按模型详情页（GET /api/v1/models/{slug}）推荐的后继版本切换。
- 如需申请 Beta，请邮件 support@ominigate.ai 并附上模型 slug 和账号 id。
image_model_not_found
HTTP 404param: model
Image model not found.
响应示例
{
"error": {
"type": "not_found_error",
"code": "image_model_not_found",
"message": "Image model not found.",
"param": "model"
}
}常见原因
- 用 /v1/images 调了聊天或 embedding 模型（如 openai/gpt-4o、openai/text-embedding-3-large）——它们无法生成图像。
- slug 正确但指向的是视频模型（如 google/veo-2），/v1/images 只接受图像生成类模型。
- 该模型是老旧图像模型，已从 Ominigate 目录中移除。
- 传入了仅有厂商名的 slug（如 openai），没有具体模型名。
处理建议
- 用 GET /api/v1/models?type=image 列出图像类模型再选择——如 openai/gpt-image-1、google/imagen-4。
- 若想生成视频，请改调 POST /v1/videos/{provider}/create；若想对话，请走 /v1/chat/completions。
- 查看模型详情页（GET /api/v1/models/{slug}），确认 output_modalities 包含 "image"。
- 始终发送完整的 provider/model slug，仅厂商名的标识符不会被接受。
video_model_not_found
HTTP 404param: model
Video model not found.
响应示例
{
"error": {
"type": "not_found_error",
"code": "video_model_not_found",
"message": "Video model not found.",
"param": "model"
}
}常见原因
- 用 /v1/videos/{provider}/{action} 调了聊天或图像模型（如 openai/gpt-4o、openai/gpt-image-1）。
- 路径中的 {provider} 与模型厂商不一致——如 POST /v1/videos/openai/create 却传 model 为 google/veo-2。
- 该视频模型已下架，或因上游故障临时停用。
- slug 合法但当前 action（create / status / result）不在该模型的工作流范围内。
处理建议
- 用 GET /api/v1/models?type=video 列出视频类模型并复制 slug——如 google/veo-2、runway/gen-4-turbo。
- 确保路径 {provider} 与模型前缀一致：google/veo-2 走 /v1/videos/google/create，runway/* 走 /v1/videos/runway/create。
- POST /v1/videos/{provider}/create 后，用返回的 task id 轮询 POST /v1/videos/{provider}/status，直到 status 为 "completed" 再调 /result。
- 如果该模型此前可用、现在才报错，请查看 status.ominigate.ai，或携带响应头 X-Request-Id 联系 support@ominigate.ai。
billing_error
HTTP 402因账单原因拒绝请求——通常是余额不足。充值后重试即可。
insufficient_balance
HTTP 402
Your balance is insufficient. Please top up your account.
响应示例
{
"error": {
"type": "billing_error",
"code": "insufficient_balance",
"message": "Your balance is insufficient. Please top up your account."
}
}常见原因
- 实时扣费（Token、图片或视频秒数）已把账户余额扣到 0 或以下。
- 长时间运行的视频轮询任务持续扣费，最终把余额耗尽。
- 最近一次充值尚未到账，可用余额仍然为 0。
- 多路并发请求在你上次查看余额之后的短时间内把余额抽干。
处理建议
- 打开 Dashboard → Billing（/dashboard/billing）充值后再重试请求。
- 充值后等待几秒让余额刷新再重试；网关每次调用都会读取最新余额。
- 为各个 API Key 配置用量上限，避免单个任务再次耗尽整个账户。
- 如果已充值但余额仍显示 0，请联系 support@ominigate.ai 并附上响应头中的 X-Request-Id。
usage_cap_exceeded
HTTP 402 / 429已触发你配置的消费上限（API Key 或账户级）。在下次重置前或提高额度前，请求会被拦截。
key_daily_limit
HTTP 429
API Key has exceeded its daily spending limit.
响应示例
{
"error": {
"type": "usage_cap_exceeded",
"code": "key_daily_limit",
"message": "API Key has exceeded its daily spending limit."
}
}常见原因
- 该 API Key 已触达你在 Dashboard 为它配置的单 Key 日预算上限。
- 该 Key 的一波请求（例如批处理任务或客户端死循环）过早耗光了日预算。
- 响应体附带 limit、used、resets_at 字段，可直接看到触顶的是哪个预算以及何时重置。
- 日预算窗口按 UTC 计算，在 UTC 00:00 重置，并非你的本地午夜。
处理建议
- 进入 Dashboard → API Keys（/dashboard/keys），点击该 Key 的用量图标调整或移除日预算。
- 把流量切到另一个尚有日预算的 API Key，或等到 resets_at 时间点后再重试。
- 重试前先在 Dashboard → Billing 确认账户余额充足，否则下一步会改触发 insufficient_balance。
- 在客户端加上退避逻辑，防止死循环几分钟内吃掉一整天的预算。
key_monthly_limit
HTTP 429
API Key has exceeded its monthly spending limit.
响应示例
{
"error": {
"type": "usage_cap_exceeded",
"code": "key_monthly_limit",
"message": "API Key has exceeded its monthly spending limit."
}
}常见原因
- 该 API Key 已触达你在 Dashboard 配置的单 Key 月度预算上限。
- 实际流量（例如生产环境新版本上线）比月度预算预估增长得更快。
- 响应体附带 limit、used、resets_at 字段，可确认触顶的月度桶和重置时间。
- 月度窗口在每月 1 日 UTC 00:00 重置，并非以 Key 的创建日为基准。
处理建议
- 如果更高月度消费在预期内，去 Dashboard → API Keys（/dashboard/keys）调高该 Key 的月度上限。
- 如果是异常飙升，先审阅该 Key 近期用量，定位调用方并暂停，再决定是否放宽上限。
- 对关键业务单独发一个带独立月预算的 API Key，避免其他流量把生产堵死。
- 自动重试可等到 resets_at，或在此之前把流量切到另一个 Key 上。
account_daily_limit
HTTP 402
Account has exceeded its daily spending limit.
响应示例
{
"error": {
"type": "usage_cap_exceeded",
"code": "account_daily_limit",
"message": "Account has exceeded its daily spending limit."
}
}常见原因
- 账户下所有 API Key 的合计日消费已触达 Dashboard → Billing 配置的账户级日上限。
- 某个或几个未单独设置上限的 Key 占用了共享日预算的大头。
- 响应体附带 limit、used、resets_at 字段，作用范围是整个账户。
- 账户日窗口在 UTC 00:00 重置，与各个 Key 自己的日窗口互相独立。
处理建议
- 如果聚合消费合理，在 Dashboard → Billing（/dashboard/billing）调高或移除账户日上限。
- 同时在 Dashboard → API Keys 给各个 Key 设单独的日上限，防止单 Key 再次垄断账户预算。
- 通过用量明细定位消费最高的 Key，先限流或停用它再考虑放开账户上限。
- 等到 resets_at 后再重试，并重新评估日上限是否匹配真实需求。
request_cost_limit
HTTP 402
Single request cost exceeds the configured limit.
响应示例
{
"error": {
"type": "usage_cap_exceeded",
"code": "request_cost_limit",
"message": "Single request cost exceeds the configured limit."
}
}常见原因
- 本次单请求的预估或实际成本超过了该 API Key 配置的单次请求成本上限。
- 超长 prompt、过大的 max_tokens、高分辨率图像或长时长视频，把这一次调用的成本顶到了上限之上。
- 响应体附带 limit（上限）和 used（本次请求成本），可直接看到超出了多少。
- 上限针对整次请求的全部成本，包括缓存写入、推理 Token 以及模型计费的工具调用。
处理建议
- 降低本次请求成本：缩短 prompt、减小 max_tokens、改用更小的模型，或请求更短的视频/更低分辨率的图像。
- 如果确实需要大额请求，去 Dashboard → API Keys（/dashboard/keys）调高该 Key 的单请求成本上限。
- 把一个大任务拆成多个小请求，每个请求都压在上限以下。
- 视频接口遇到该错误时请停止轮询——后续不会再扣费，但当前这次调用已经被拒绝。
日上限错误会附带额外字段（limit / used / resets_at）。完整响应格式与配置方法请查看「用量封顶」文档。
rate_limit_error
HTTP 429触发频率限制以保护平台不被突发流量压垮。请按 Retry-After（若有）退避，或采用指数退避重试。
rate_limited
HTTP 429
Rate limit exceeded.
响应示例
{
"error": {
"type": "rate_limit_error",
"code": "rate_limited",
"message": "Rate limit exceeded."
}
}常见原因
- 触发了平台级的总量限流，用于保护网关整体稳定性。
- 同一账户下多个 Key 同时出现流量高峰，合计超过了平台的综合阈值。
- 上游供应商暂时抖动，Ominigate 临时收紧了限流以维持服务可用性。
- 客户端不带退避地自动重试，把原本的小波动放大成持续被限流的状态。
处理建议
- 使用指数退避（例如 1s、2s、4s、8s 并加抖动）重试，并遵守响应头中的 Retry-After。
- 把突发流量分摊到更长的时间窗内，或在客户端排队，不要一口气并发发出去。
- 如果限流集中在某个 Key 上，先检查是否同时收到 rpm_rate_limited 或 tpm_rate_limited，并优先调整它们。
- 如果常态流量下仍持续报错，请联系 support@ominigate.ai 并附上响应头中的 X-Request-Id。
rpm_rate_limited
HTTP 429
Rate limit exceeded: requests per minute.
响应示例
{
"error": {
"type": "rate_limit_error",
"code": "rpm_rate_limited",
"message": "Rate limit exceeded: requests per minute."
}
}常见原因
- 该 API Key 超过了 Dashboard 配置的 RPM（每分钟请求数）上限。
- 大量短小、低 Token 的请求并发发出，即使 TPM 还有富余也会先打满 RPM。
- 轮询循环（例如视频接口的 polling）拉得太紧，把 RPM 预算耗光。
- 客户端对 4xx 错误立即重试，一次失败被放大成每分钟几十次请求。
处理建议
- 如果该流量模式是预期的，进入 Dashboard → API Keys（/dashboard/keys）调高该 Key 的 RPM。
- 在客户端加并发控制：限制在途请求数量，其余排队，不要同时发出去。
- 视频轮询请遵循接口建议的间隔并做指数退避，不要比推荐节奏更快。
- 按指数退避（例如 1s、2s、4s 并加抖动）重试，并遵守 429 响应中的 Retry-After 头。
tpm_rate_limited
HTTP 429
Rate limit exceeded: tokens per minute.
响应示例
{
"error": {
"type": "rate_limit_error",
"code": "tpm_rate_limited",
"message": "Rate limit exceeded: tokens per minute."
}
}常见原因
- 该 API Key 超过了 Dashboard 配置的 TPM（每分钟 Token 数）上限。
- 超长 prompt 或较大的 max_tokens 让每分钟的 Token 总量冲破了上限，即使请求数并不多。
- 带有超大上下文的流式对话，其返回 Token 会全量计入 TPM。
- 把大文档喂给模型的批处理任务把大量 Token 集中塞进同一分钟窗口。
处理建议
- 如果更高的 Token 吞吐是预期的，去 Dashboard → API Keys（/dashboard/keys）调高该 Key 的 TPM。
- 降低单次调用的 Token 消耗：精简 prompt、启用支持的 prompt 缓存、或降低 max_tokens。
- 把大任务在时间上摊开，让任一 60 秒窗口内的 Token 量都低于 TPM。
- 按指数退避重试并遵守 Retry-After 头；立即重试只会再次撞上 TPM。
upstream_error
HTTP 502 / 504网关已连通上游厂商，但厂商返回失败、超时或不可达。多数属于瞬时故障，建议退避后重试。
upstream_failed
HTTP 502
Upstream request failed.
响应示例
{
"error": {
"type": "upstream_error",
"code": "upstream_failed",
"message": "Upstream request failed."
}
}常见原因
- 网关到上游厂商的单次请求失败（连接被重置、TLS 握手错误，或厂商返回 5xx）。
- 网关与上游之间出现瞬时网络抖动，导致请求在传输过程中中断。
- 上游厂商对网关出口 IP 做了短暂限流或熔断。
- 如果使用 stream=true 流式请求，SSE 连接在最后一个 chunk 到达前被断开。
处理建议
- 按指数退避重试请求（initial=1s, factor=2, 带 jitter, max=30s，最多 3-5 次）。绝大多数请求在第二次就会成功。
- 若是流式请求在中途断开，请记录收到的最后一个 chunk，然后重新发送一次完整请求——网关不支持流的中途续传。
- 保留响应头中的 X-Request-Id，反馈给 support@ominigate.ai 时一并附上。
- 如果同一个模型持续重试失败，可临时切换到其他厂商提供的同类模型作为降级方案。
image_generation_failed
HTTP 502
Image generation failed.
响应示例
{
"error": {
"type": "upstream_error",
"code": "image_generation_failed",
"message": "Image generation failed."
}
}常见原因
- 上游图像生成接口返回错误（提示词不符合厂商政策、渲染失败，或厂商返回 5xx）。
- 提示词或参考图被厂商的内容安全过滤器拒绝。
- 所请求的图像尺寸、数量 n 或格式不被该模型支持。
- 厂商在本次生成任务中发生了瞬时故障。
处理建议
- 按指数退避重试（initial=1s, factor=2, 带 jitter, max=30s，最多 3 次），单次故障绝大多数可通过重试恢复。
- 部分上游在失败时仍会扣费，若重试后成功，请对照用量明细；如存在重复计费，请带上 X-Request-Id 邮件 support@ominigate.ai 申请调整。
- 若问题稳定复现，请简化提示词、降低图像尺寸或减少 n 后再试。
- 如果只有某个特定模型持续失败，可从 /v1/models 中换一个图像模型。
image_generation_timeout
HTTP 504
Image generation timed out.
响应示例
{
"error": {
"type": "upstream_error",
"code": "image_generation_timeout",
"message": "Image generation timed out."
}
}常见原因
- 上游图像生成任务超出了网关的超时阈值，但厂商侧任务本身可能仍在执行中。
- 上游负载过高，渲染队列积压。
- 所选模型或请求的分辨率本身计算开销较大，合理耗时超过了超时窗口。
- 网关到厂商之间的网络链路变慢，响应在超时后才到达。
处理建议
- 请勿立即重试——上游任务可能仍在运行，盲目重试会造成重复计费。把它当成「结果未知」而不是「已失败」。
- 把响应头中的 X-Request-Id 邮件 support@ominigate.ai，我们会查询上游任务状态，确认是否已完成。
- 在 support 确认任务未完成后，再按指数退避重试（initial=1s, factor=2, 带 jitter, max=30s，最多 3 次）。
- 为降低超时风险，可降低图像分辨率、减少 n，或从 /v1/models 选择一个更快的模型。
video_generation_failed
HTTP 502
Video generation failed.
响应示例
{
"error": {
"type": "upstream_error",
"code": "video_generation_failed",
"message": "Video generation failed."
}
}常见原因
- 上游视频生成厂商拒绝了提交请求（提示词非法、参数组合不受支持，或其 API 返回 5xx）。
- 厂商的安全过滤器拒绝了提示词、参考图或起始视频帧。
- 所请求的时长、分辨率或宽高比不被该模型支持。
- 提交阶段出现了瞬时网络或上游故障。
处理建议
- 按指数退避重试提交（initial=1s, factor=2, 带 jitter, max=30s，最多 3 次）——此时任务尚未在上游创建，重试不会造成重复扣费。
- 若问题稳定复现，请简化提示词、缩短时长或降低分辨率，保证参数落在该模型支持范围内。
- 若相同载荷反复失败，请将 X-Request-Id 发给 support@ominigate.ai。
- 如果某个厂商持续不稳定，可从 /v1/models 临时切换到其他视频模型。
video_task_id_missing
HTTP 502
Upstream returned success but task ID is missing.
响应示例
{
"error": {
"type": "upstream_error",
"code": "video_task_id_missing",
"message": "Upstream returned success but task ID is missing."
}
}常见原因
- 上游视频厂商对提交接口返回了 HTTP 200，但响应体中缺少 task_id 字段。
- 厂商在未通知的情况下改动了响应结构，网关尚未适配。
- 上游存在瞬时 bug，在序列化阶段意外丢掉了 task_id。
- 厂商接受了提交，但任务被创建在一个没有可寻址 ID 的异常内部状态下。
处理建议
- 请重新提交请求——没有 task_id 就无法轮询或取消任务，需要新的提交拿到可用的任务句柄。
- 按指数退避重试（initial=1s, factor=2, 带 jitter, max=30s，最多 3 次）；每次提交之间保留适当间隔，避免在上游留下孤儿任务。
- 将 X-Request-Id 和受影响的厂商/模型发送给 support@ominigate.ai，我们会向上游厂商报故障。
- 如果短时间内同一个厂商反复出现此错误，请先切换到其他视频模型，等待上游修复。
internal_error
HTTP 500OminiGate 自身出现异常，发生概率应当很低。如遇到请连同响应头 X-Request-Id 一起反馈给我们。
internal_error
HTTP 500
Internal server error.
响应示例
{
"error": {
"type": "internal_error",
"code": "internal_error",
"message": "Internal server error."
}
}常见原因
- 网关自身出现未预期的 bug 或未捕获异常（不是业务拒绝，而是内部缺陷）。
- 网关依赖的组件（数据库、缓存、内部 RPC）在处理请求时短暂失败。
- 近期的发布引入了回归，恰好影响了你这次请求走到的代码路径。
- 网关侧资源（CPU、内存、连接池）紧张，导致请求中途失败。
处理建议
- 按指数退避重试（initial=1s, factor=2, 带 jitter, max=30s，最多 3-5 次）——绝大多数 internal_error 是瞬时的，下一次就会成功。
- 请务必保留响应头中的 X-Request-Id 并发给 support@ominigate.ai，我们据此定位完整调用栈并修复根因。
- 若相同载荷持续复现，请在工单邮件中附上最小化 curl 复现脚本，能显著加速排查。
- 留意 https://status.ominigate.ai（或内部状态渠道）是否有与你失败时间吻合的进行中故障。
video_billing_error
HTTP 500
Failed to calculate video cost.
响应示例
{
"error": {
"type": "internal_error",
"code": "video_billing_error",
"message": "Failed to calculate video cost."
}
}常见原因
- 视频任务已在上游完成，但网关的计费模块在计算或落账时失败（数据库超时、decimal 溢出，或缺少定价条目）。
- 视频任务成功产出，但计费器遇到一个意料外的模型/参数组合，无法定价。
- 瞬时的数据库或缓存故障，导致计费事务无法提交。
- 定价配置发布存在竞态，任务完成那一刻模型没有有效的定价条目。
处理建议
- 请勿重新提交视频任务——它在上游大概率已经成功产出，重复提交会为同一段输出二次扣费。
- 请立即将 X-Request-Id 和视频 task_id 邮件 support@ominigate.ai，我们会人工对账计费记录，并确认产物是否可获取。
- 等待对账期间，你通常仍可使用已持有的 task_id 通过标准轮询接口获取已完成的视频。
- 后续新的视频请求可以正常发起——该错误仅发生在计费后处理阶段，不会阻塞新提交。
没找到你的错误码？
请把完整响应体和响应头 X-Request-Id 发到 support@ominigate.ai，我们会在一个工作日内回复。