错误与重试
最近更新：2026年9月1日
Amux API 的错误类型、故障转移、客户端重试与计费规则。
Amux 按调用协议返回兼容的错误格式。每个错误都包含 request_id，联系支持时可用它定位请求。
错误类型
| 类型 | HTTP | 归因 | 网关故障转移 |
|---|---|---|---|
| invalid_request | 400 | 调用方 | 否 |
| context_length_exceeded | 400 | 调用方 | 否 |
| authentication | 401 | 调用方 | 否 |
| insufficient_credits | 402 | 调用方 | 否 |
| permission_denied | 403 | 调用方 | 否 |
| content_policy_violation | 403 | 调用方 | 否 |
| request_timeout | 408 | 上游 | 是 |
| rate_limit_exceeded | 429 | 调用方 | 否 |
| provider_rate_limited | 502 | 上游 | 是 |
| provider_error | 502 | 上游 | 是 |
| provider_overloaded | 502 | 上游 | 是 |
| provider_account_issue | 502 | 上游 | 否 |
| not_found | 404 | 调用方 | 否 |
| no_available_provider | 503 | 平台 | 否 |
| overloaded | 503 | 平台 | 否 |
| internal_error | 500 | 平台 | 否 |
“归因”表示错误来自哪一侧：
- 调用方：请求、鉴权、余额或用量限制有误。更换供应商无法解决
- 上游：供应商超时、限流、过载或返回异常
- 平台：Amux 暂时无法处理请求，或当前没有可用供应商
“网关故障转移”表示 Amux 是否可以在响应开始前尝试其他可用供应商。它不代表客户端会自动重试，也不保证一定存在可切换的供应商。
客户端重试
收到错误后是否重试，应根据错误类型和响应头判断：
- 调用方错误通常需要修改请求、充值或等待限额恢复，直接重试一般无效
- 上游或平台暂时不可用时，可以退避后重试
- 响应包含
Retry-After时，至少等待指定时间再重试
流式响应一旦开始，网关不会切换供应商。此后发生的中断由客户端决定是否重新发起请求。
no_available_provider 的三种情形
这个类型覆盖「请求没有落到任何一条可用链路上」，而三种情形的处置完全不同——以响应里的说明为准，不要只看错误码：
| 说明里出现 | 含义 | 该做什么 |
|---|---|---|
Use POST /v1/tasks instead（或其它具体指引） | 这个模型在当前端点上生成不了，但换一条端点可以 | 按说明改调用方式，重试当前端点无效 |
temporarily unavailable while its upstream connections recover | 上游连接正在恢复中 | 退避后重试，通常很快恢复 |
This is on our side | 需要我们这边处理 | 带上 request_id 联系我们；说明里写明「重试无效」时，重试不会有帮助 |
计费
- 故障转移中失败的尝试不计费；请求最终成功时，只收取成功结果的费用
- 客户端中途断开时，已经产生的用量仍会计费
- 图像、视频等媒体任务执行失败不计费
错误响应
错误体与调用协议保持兼容：OpenAI 兼容端点返回 OpenAI 格式，Anthropic Messages 返回 Anthropic 格式，Gemini 返回 Google RPC 格式。
调用方错误会保留必要的可操作信息。上游和平台故障只返回稳定的公开说明，供应商原始报文仅用于服务端排障。所有格式都会返回 request_id。