错误处理

错误处理先看 HTTP 状态和当前入口语境，再决定是否重试。OpenAI 兼容入口的本地错误使用 error.message、error.type 和 error.code；Anthropic 兼容入口的本地错误使用 Anthropic 错误信封， 不要假定其中存在 code 字段。

本地错误与动作

invalid_api_key

• 常见触发：Key 缺失、无效或已停用。
• 建议动作：检查当前环境的鉴权头和 Key 状态。
• 自动重试：否；重复风险：无。

model_not_found

• 常见触发：模型未上架或当前不可用。
• 建议动作：从实时模型目录重新选择。
• 自动重试：否；重复风险：无。

insufficient_balance

• 常见触发：通用余额不足。
• 建议动作：补足余额后由业务明确发起新请求。
• 自动重试：否；重复风险：低。

balance_daily_limit_exceeded

• 常见触发：余额日限额已触发。
• 建议动作：调整限额或等待下个自然日。
• 自动重试：否；重复风险：无。

insufficient_package

• 常见触发：Coding Plan 权益不足。
• 建议动作：检查套餐状态与可用额度。
• 自动重试：否；重复风险：低。

package_expired

• 常见触发：Coding Plan 已过期。
• 建议动作：恢复有效套餐后重新决定请求。
• 自动重试：否；重复风险：低。

model_not_in_package

• 常见触发：模型不在当前套餐范围。
• 建议动作：切换套餐支持模型或选择通用余额入口。
• 自动重试：否；重复风险：无。

package_5h_quota_exhausted

• 常见触发：五小时套餐额度耗尽。
• 建议动作：等待窗口恢复或调整套餐。
• 自动重试：否；重复风险：无。

package_weekly_quota_exhausted

• 常见触发：周套餐额度耗尽。
• 建议动作：等待周期恢复或调整套餐。
• 自动重试：否；重复风险：无。

package_concurrency_limited

• 常见触发：套餐并发上限已满。
• 建议动作：降低并发并进行有界排队。
• 自动重试：是，退避后；重复风险：低。

package_input_too_large

• 常见触发：Coding Plan 输入字节超限。
• 建议动作：缩短或拆分输入。
• 自动重试：否；重复风险：无。

package_output_limit_exceeded

• 常见触发：请求要求的输出超出套餐边界。
• 建议动作：降低输出要求或调整方案。
• 自动重试：否；重复风险：无。

invalid_request_error

• 常见触发：请求结构、必填字段或本地校验不满足。
• 建议动作：修正请求后重新发送。
• 自动重试：否；重复风险：无。

upstream_error

• 常见触发：上游连接异常或非 2xx 响应。
• 建议动作：记录请求意图，按业务幂等性决定有界重试。
• 自动重试：视情况；重复风险：中到高。

upstream_timeout

• 常见触发：上游超时。
• 建议动作：先确认业务是否允许未知结果重放。
• 自动重试：视情况；重复风险：中到高。

internal_error

• 常见触发：平台内部错误。
• 建议动作：保留 trace 信息并稍后重试或联系支持。
• 自动重试：视情况；重复风险：中到高。

上游错误

上游响应和非 2xx 错误不能按本地错误码穷尽。数据面会保留协议兼容的开放边界，因此客户端应把 502、504 和未知供应商状态视为“执行结果可能未知”，而不是只按某个字符串做判断。

重试前的判断

1. 在尚未收到任何流内容前，检查操作是否能安全重复及业务是否有幂等键。
2. 已收到部分流内容时，不要无条件重放同一请求。
3. 认证、模型、余额、套餐和请求结构问题必须先修正根因。

详细规则见流式与重试。