error.code 和 HTTP 状态进行分支处理,而不是根据消息文本。每个 Phaseo 错误在所有端点上都有相同的 JSON 正文,其 error 对象(code、message、type、param)正是 OpenAI 兼容 SDK 读取的格式,因此这些 SDK 抛出的异常会带有 Phaseo 的消息。
{
"error": {
"code": "upstream_error",
"message": "Provider \"google-ai-studio\" failed with HTTP 403 for endpoint \"responses\" on model \"google/gemini-2.5-pro\".",
"type": "server_error",
"param": null,
"metadata": {
"reason": "all_candidates_failed",
"attempt_count": 1,
"failed_providers": ["google-ai-studio"],
"failed_statuses": [403],
"upstream_error": {
"code": "PERMISSION_DENIED",
"message": "The caller does not have permission.",
"description": null,
"param": null
}
}
},
"code": "upstream_error",
"message": "Provider \"google-ai-studio\" failed with HTTP 403 for endpoint \"responses\" on model \"google/gemini-2.5-pro\".",
"generation_id": "G-abc123",
"status_code": 502,
"error_type": "system",
"error_origin": "upstream",
"reason": "all_candidates_failed",
"description": "Provider \"google-ai-studio\" failed with HTTP 403 for endpoint \"responses\" on model \"google/gemini-2.5-pro\".",
"attempt_count": 1,
"failed_providers": ["google-ai-studio"],
"failed_statuses": [403],
"provider_failure_diagnostics": {
"category": "provider_access_missing",
"hint": "The provider account appears not to have access to this model or feature yet. Verify account entitlements and provider-side access.",
"provider": "google-ai-studio"
},
"upstream_error": {
"code": "PERMISSION_DENIED",
"message": "The caller does not have permission.",
"description": null,
"param": null
},
"failure_sample": [
{
"provider": "google-ai-studio",
"type": "upstream_non_2xx",
"status": 403,
"upstream_error_code": "PERMISSION_DENIED",
"upstream_error_message": "The caller does not have permission.",
"upstream_error_description": null,
"upstream_error_param": null,
"upstream_payload_preview": "{\"error\":{\"status\":\"PERMISSION_DENIED\"}}",
"retryable": false
}
]
}
每个错误都包含的字段
| 字段 | 内容 |
|---|---|
error.code | 机器可读的代码,例如 validation_error。请参阅错误代码。 |
error.message | 通俗易懂的说明。 |
error.type | 错误类别,根据 HTTP 状态设置。请参阅错误类型。 |
error.param | 导致错误的请求字段(如果 Phaseo 知道);否则为 null。 |
error.metadata | 可选。结构化的详细信息,例如 reason、failed_providers、failed_statuses 或 retry_after_seconds。相同的值也会出现在顶层。 |
code | 与 error.code 相同。旧的响应会将这个字符串放在 error 中返回;如果你的客户端在那里期望一个字符串,请读取 code。 |
message、description | 与 error.message 的文本相同。 |
generation_id | 用于记录日志和提供给支持团队的请求 ID。 |
status_code | HTTP 状态。 |
error_type | user 或 system。 |
error_origin | 问题的来源:调用方(user)、Phaseo(gateway)或提供商(upstream)。 |
details | 可选。请求正文无效时的校验详情。 |
| 字段 | 何时出现 |
|---|---|
reason | 具体的子原因,例如 all_candidates_failed 或 no_provider_pricing。 |
provider_failure_diagnostics | 已连接到提供商但请求失败。请参阅提供商失败时。 |
upstream_error、failure_sample | 第一次提供商失败的尽力而为的摘要。 |
failed_providers、failed_statuses、attempt_count | 尝试了哪些提供商以及它们返回了什么。 |
provider_candidate_diagnostics、provider_enablement、routing_diagnostics | 没有提供商能在此端点上提供该模型。请参阅模型或端点不可用时。 |
错误类型
error.type 遵循 OpenAI 记录的错误类型,并根据 HTTP 状态设置:
| 状态 | error.type |
|---|---|
401 | authentication_error |
402 | insufficient_quota |
403 | permission_error |
404 | not_found_error |
429 | rate_limit_error |
408、500、502 和其他 5xx | server_error |
503 | service_unavailable |
529 | overloaded |
400、409、410、413、422 和其他 4xx | invalid_request_error |
/v1/messages 上的错误使用相同的正文,因此 Anthropic SDK 也能找到 error.type 和 error.message。
错误代码
error.code | 状态 | 含义 | 处理方法 |
|---|---|---|---|
validation_error | 400 | 某个参数或请求正文无效。error.param 指出第一个无效字段。 | 修正请求。 |
invalid_json | 400 | 正文不是有效的 JSON。 | 修正请求。 |
model_required | 400 | 请求中没有 model。 | 添加 model。 |
unsupported_model_or_endpoint | 400 | 没有提供商能在此端点上提供该模型。 | 请参阅下文。 |
unsupported_modalities | 400 | 没有路由接受请求中的输入或输出类型。 | 更换模型或输入。 |
byok_credentials_required | 400 | 该路由只能使用你自己的提供商密钥运行。 | 添加符合条件的提供商密钥。 |
upstream_error | 400、413 或 422 | 所有提供商都以相同的状态拒绝了请求(reason 为 upstream_rejected_request)。 | 修正请求;重试没有帮助。 |
unauthorised | 401 | 密钥缺失或无效。reason 说明原因。 | 检查 Authorization 标头。 |
insufficient_funds | 402 | 工作区没有足够的额度。 | 充值额度。 |
pricing_not_configured | 402 | 该模型没有任何提供商配置了定价(reason 为 no_provider_pricing)。 | 选择其他模型。 |
guardrail_blocked | 403 | 护栏或访问策略阻止了请求。 | 修改请求或护栏。 |
model_region_unavailable | 403 | 没有提供商在所需区域提供该模型,或无法从调用方所在位置提供。 | 放宽区域要求或选择其他模型。 |
not_found | 404 | 端点或资源不存在。 | 检查路径和 ID。 |
not_ready | 409 | 任务的结果尚未就绪。 | 轮询任务的状态。 |
model_retired | 410 | 模型已退役,且没有提供商提供它。 | 切换到 replacement_model。请参阅下文。 |
payload_too_large | 413 | 正文大于端点接受的大小。max_bytes 给出上限。 | 发送更小的正文或上传文件。 |
key_limit_exceeded | 429 | 达到了密钥限制、预算或 Gateway 每分钟限制。 | 请参阅速率限制。 |
phaseo_free_model_limit_exceeded | 429 | 免费模型的每日配额(默认 1,500 次请求)已用完。 | 遵守 Retry-After,等待 00:00 UTC 重置,或使用付费模型。 |
rate_limit_exceeded | 429 | 某个工作区速率限制策略已耗尽。policy_id 和 limit_scope 标识该策略。 | 遵守 Retry-After,或请管理员修改策略。 |
spend_rule_blocked | 429 | 一条设为阻止的支出规则正在生效。 | 遵守 Retry-After,或请所有者或管理员解除阻止。 |
upstream_error | 429 | 尝试的所有提供商都对请求进行了限流。 | 遵守 Retry-After。BYOK 请求还会携带 X-Phaseo-Upstream-RateLimit-* 标头。 |
provider_capacity_exhausted | 429 | 所有符合条件的提供商都已满负荷(reason 为 all_candidates_rate_limited)。 | 如果存在 Retry-After 则遵守它,否则退避。 |
gateway_error | 500 | Phaseo 内部出现故障。 | 使用退避重试。 |
not_implemented_yet | 501 | 该操作尚不可用。 | 不要重试。 |
upstream_error | 502 | 提供商未能正确响应。 | 使用退避重试。 |
upstream_stream_failure | 502 | 非流式请求的提供商在开始生成后失败。不会返回部分输出,也不会对该请求收费。 | 重试。 |
provider_payment_required | 502 | Phaseo 在该提供商的账户需要处理。 | 稍后重试或报告该问题。 |
只重试应当重试的错误
| 状态 | 是否重试? |
|---|---|
除 429 外的 400–499 | 否。先修正请求、密钥或访问权限。 |
429 | 是。等待 Retry-After(秒数或 HTTP 日期),否则使用带抖动的指数退避。没有 Retry-After 的 key_limit_exceeded 错误不会自动重置,因此不要重试。 |
500–599 | 仅当重复该操作是安全的时候。结果不明确的提交可能已经创建了任务或产生了费用;请查找已被接受的任务,而不是再次提交。 |
提供商失败时
当 Phaseo 已连接到提供商但请求仍然失败时,provider_failure_diagnostics 包含 category、hint 和 provider。类别如下:
category | 含义 |
|---|---|
credentials_not_configured | 此路由没有设置凭据。 |
credentials_invalid_or_forbidden | 凭据被拒绝。 |
provider_access_missing | 提供商账户无权访问该模型或功能。 |
region_or_project_restriction | 提供商因区域或项目原因拒绝。 |
model_unavailable_for_endpoint | 提供商未在此端点上提供该模型。 |
rate_limited | 提供商对请求进行了限流。 |
server_error | 提供商失败或超时。 |
模型或端点不可用时
unsupported_model_or_endpoint 错误可能包含 provider_candidate_diagnostics、provider_enablement、missing_pricing_providers 和 routing_diagnostics。它们结合起来可以区分以下情况:模型尚未启用、模型不支持该端点、缺少定价,以及上线限制。
| 字段 | 含义 |
|---|---|
provider_candidate_diagnostics.totalProviders | 端点筛选之前该模型已知的提供商。 |
provider_candidate_diagnostics.supportsEndpointCount | 支持所请求端点的提供商。 |
provider_candidate_diagnostics.candidateCount | 适配器检查后剩余的提供商。 |
provider_candidate_diagnostics.droppedUnsupportedEndpoint | 因不支持该端点而被剔除的提供商。 |
provider_candidate_diagnostics.droppedMissingAdapter | 因 Phaseo 尚无该端点的适配器而被剔除的提供商和端点组合。 |
provider_enablement.capability | 正在执行的能力,例如 video_generation。 |
provider_enablement.providersBefore、providersAfter | 能力筛选之前和之后的提供商。 |
provider_enablement.dropped[].reason | 提供商被剔除的原因,例如 pricing_missing。 |
routing_diagnostics.filterStages[].stage | 一个路由阶段,例如能力、上线或路由状态筛选。 |
routing_diagnostics.filterStages[].beforeCount、afterCount | 该阶段之前和之后的提供商。 |
routing_diagnostics.filterStages[].droppedProviders[].reason | 提供商在该阶段被剔除的原因。 |
{
"error": {
"code": "unsupported_model_or_endpoint",
"message": "No provider is currently routable for endpoint \"responses\" on model \"example/model\".",
"type": "invalid_request_error",
"param": null
},
"code": "unsupported_model_or_endpoint",
"generation_id": "G-unsupported123",
"status_code": 400,
"description": "No provider is currently routable for endpoint \"responses\" on model \"example/model\".",
"provider_candidate_diagnostics": {
"totalProviders": 3,
"supportsEndpointCount": 2,
"candidateCount": 1,
"droppedUnsupportedEndpoint": ["provider-a"],
"droppedMissingAdapter": [
{
"providerId": "provider-b",
"endpoint": "responses"
}
]
},
"provider_enablement": {
"capability": "responses",
"providersBefore": ["provider-b", "provider-c"],
"providersAfter": ["provider-c"],
"dropped": [
{
"providerId": "provider-b",
"reason": "pricing_missing"
}
]
},
"routing_diagnostics": {
"filterStages": [
{
"stage": "provider_routing_status",
"beforeCount": 1,
"afterCount": 0,
"droppedProviders": [
{
"providerId": "provider-c",
"reason": "provider_status_not_ready"
}
]
}
]
}
}
模型退役时
只要还有任何提供商提供已退役的模型,它就仍然可用。一旦没有提供商提供,请求就会以410 和 model_retired 失败:
{
"error": {
"code": "model_retired",
"message": "Model \"lab/old-model\" was retired on 2026-09-30 and no provider serves it any more. Use \"lab/new-model\" instead.",
"type": "invalid_request_error",
"param": null,
"metadata": {
"retired_at": "2026-09-30T00:00:00Z",
"replacement_model": "lab/new-model"
}
},
"code": "model_retired",
"generation_id": "G-retired123",
"status_code": 410,
"reason": "model_retired_without_providers",
"description": "Model \"lab/old-model\" was retired on 2026-09-30 and no provider serves it any more. Use \"lab/new-model\" instead.",
"model": "lab/old-model",
"retired_at": "2026-09-30T00:00:00Z",
"replacement_model": "lab/new-model"
}
model 是你请求的模型,retired_at 是它退役的时间(或 null),replacement_model 是建议的替代模型(或 null)。
重试没有帮助;请更改模型 ID。要在迁移期间让这些请求继续工作,请将替代模型添加到请求的 models 列表中,或为工作区开启已退役模型路由。请参阅模型弃用与退役。
流式传输期间的错误
如果请求在流式传输开始之前失败,你会收到上文的 JSON 错误正文。如果在流式传输中途失败,流会以该端点的失败事件结束,而不是正常结束:| 端点 | 失败事件 |
|---|---|
| Chat Completions | 一个 error 帧 |
| Responses | response.failed(或 error) |
| Messages | 一个 error 事件 |
error 帧携带相同的错误对象,error.type 根据代码设置:
{
"object": "error",
"message": "The upstream stream ended before the response completed.",
"code": "upstream_stream_failure",
"error": {
"code": "upstream_stream_failure",
"message": "The upstream stream ended before the response completed.",
"type": "server_error",
"param": null
}
}
502 和 upstream_stream_failure,而不是部分响应。请参阅流式传输。
调试请求
发送一个debug 对象,即可获得路由追踪和上游载荷:
{
"debug": {
"enabled": true,
"return_upstream_request": true,
"return_upstream_response": false,
"trace": true,
"trace_level": "summary"
}
}
trace_level 为 summary 或 full。调试载荷可能包含你的请求内容,因此只应在开发环境或严格受控的环境中使用。请参阅 debug。
请求失败时,请查看状态页面了解是否有事故,将你的载荷与该端点的参考页面进行比较,并将 generation_id 与端点和模型一起记录到日志中。联系支持团队时请附上 generation_id。