跳转到主要内容
根据 error.code 和 HTTP 状态进行分支处理,而不是根据消息文本。每个 Phaseo 错误在所有端点上都有相同的 JSON 正文,其 error 对象(code、message、type、param)正是 OpenAI 兼容 SDK 读取的格式,因此这些 SDK 抛出的异常会带有 Phaseo 的消息。

每个错误都包含的字段

有些错误会添加更多上下文:

错误类型

error.type 遵循 OpenAI 记录的错误类型,并根据 HTTP 状态设置: /v1/messages 上的错误使用相同的正文,因此 Anthropic SDK 也能找到 error.type 和 error.message。

错误代码

只重试应当重试的错误

设置尝试次数上限和总体截止时间。速率限制标头请参阅速率限制。

提供商失败时

当 Phaseo 已连接到提供商但请求仍然失败时,provider_failure_diagnostics 包含 category、hint 和 provider。类别如下:

模型或端点不可用时

unsupported_model_or_endpoint 错误可能包含 provider_candidate_diagnostics、provider_enablement、missing_pricing_providers 和 routing_diagnostics。它们结合起来可以区分以下情况:模型尚未启用、模型不支持该端点、缺少定价,以及上线限制。

模型退役时

只要还有任何提供商提供已退役的模型,它就仍然可用。一旦没有提供商提供,请求就会以 410 和 model_retired 失败:
model 是你请求的模型,retired_at 是它退役的时间(或 null),replacement_model 是建议的替代模型(或 null)。 重试没有帮助;请更改模型 ID。要在迁移期间让这些请求继续工作,请将替代模型添加到请求的 models 列表中,或为工作区开启已退役模型路由。请参阅模型弃用与退役。

流式传输期间的错误

如果请求在流式传输开始之前失败,你会收到上文的 JSON 错误正文。如果在流式传输中途失败,流会以该端点的失败事件结束,而不是正常结束: 将部分输出视为不完整,并提供重试选项。Chat Completions 的 error 帧携带相同的错误对象,error.type 根据代码设置:
非流式请求的提供商中途失败时,会返回 502 和 upstream_stream_failure,而不是部分响应。请参阅流式传输。

调试请求

发送一个 debug 对象,即可获得路由追踪和上游载荷:
trace_level 为 summary 或 full。调试载荷可能包含你的请求内容,因此只应在开发环境或严格受控的环境中使用。请参阅 debug。 请求失败时,请查看状态页面了解是否有事故,将你的载荷与该端点的参考页面进行比较,并将 generation_id 与端点和模型一起记录到日志中。联系支持团队时请附上 generation_id。
最后修改于 2026年11月5日