Skip to content

错误码与响应说明 ​

平台 API 错误响应结构、HTTP 状态码、上游错误穿透策略、脱敏规则与排查方式

错误响应结构 ​

平台 API 失败时会返回错误对象。不同兼容协议可能会保持对应协议的外层形态,但核心字段语义一致。

json
{
  "error": {
    "code": "invalid_request_error",
    "message": "Invalid image size. The longest edge must be <= 4096. (request id: 20260604120000abcdef)",
    "type": "invalid_request_error",
    "request_id": "20260604120000abcdef",
    "upstream_request_id": "req_abc123"
  }
}
字段说明
error.code程序可识别的错误码;多数上游业务错误会保留上游语义
error.message可展示给终端用户或记录到业务日志的安全文案
error.type错误大类;多数上游业务错误会保留上游语义
error.request_id平台请求 ID,提交工单时优先提供
error.upstream_request_id上游请求 ID,如上游返回则提供

对外策略 ​

平台采用“默认穿透、证据包装”的错误输出策略。

场景输出策略
官方或严格兼容渠道默认保留上游 status、type、code、可读 message,仅追加平台 request_id 并清理敏感片段
可信代理渠道默认清洗后穿透;会更积极移除 URL、SDK、内部 request id、租户或账号等实现细节
未配置渠道默认按官方或严格兼容渠道处理
上游账号、Key、权限、余额、billing、quota视为运营供给问题,统一包装为上游渠道或容量暂不可用
清洗后仍无法安全表达的内部泄漏使用平台安全文案包装,不直接展示原始上游错误

INFO

custom_parameter.public_error_trust_level 可配置为 official 或 trusted_proxy。未配置时默认为 official。

HTTP 状态码 ​

状态码平台固定语义上游错误处理
400客户请求参数错误、模型能力不支持、内容输入问题通常保留上游 400 与可读语义
401平台 API Key 无效或缺失上游账号或 Key 错误不会作为客户 401 直接返回
402平台账户、令牌或组织额度不足上游余额、billing、quota 会包装为 503
403平台侧无权访问模型、分组、IP 白名单或资源上游权限、账号封禁、Key 无权访问会包装为 503
429平台或上游触发限流默认保留 429 与上游限流语义,清理敏感片段
502上游服务返回异常、坏响应或网关错误默认保留或清洗后穿透
503上游渠道账号、权限、余额、计费、容量等供给暂不可用平台包装后的运营供给类错误
504上游超时或网络连接问题默认保留或清洗后穿透

平台包装错误 ​

以下错误由平台稳定包装,避免客户误判为自身权限或看到运营侧供给细节。

error.typeerror.code含义建议处理
system_errorupstream_channel_unavailable上游渠道账号、Key、权限、账号状态暂不可用稍后重试;持续出现请提交工单
system_errorupstream_capacity_unavailable上游渠道余额、billing、quota、容量或供给暂不可用稍后重试;持续出现请提交工单

其他上游业务错误,例如内容安全、限流、超时、5xx、模型能力不支持、图片尺寸错误、上下文长度错误,第一版默认穿透或清洗后穿透,不强制统一成平台 code/type。

内容安全与生图封控 ​

当上游明确返回内容安全或生图封控原因时,平台会尽量保留客户可理解的语义,让客户知道需要修改输入内容。

平台不会直接暴露上游内部字段,例如:

上游内部信号客户可见处理
finishReason=IMAGE_SAFETY移除内部字段,保留“图片被安全策略过滤”等可理解语义
finishReason=PROHIBITED_CONTENT移除内部字段,保留内容安全语义
promptFeedback.blockReason=PROHIBITED_CONTENT移除内部字段,保留输入内容未通过安全检查语义
no candidates / empty_candidates清理实现细节,保留上游可读原因或平台安全文案

封控类错误不再默认强制改写为 content_policy_error。如果上游本身返回了清晰的内容安全 type、code 或状态码,平台会优先保留。

no_image_generated 与 usage ​

Gemini 图像模型可能出现“上游已处理请求、返回 usage,但最终没有生成图片”的结果。此时平台会返回 error.code=no_image_generated。

如果本次请求已经按 prompt/input tokens 完成结算,客户可见响应会附带本次 usage:

接口风格usage 字段
OpenAI 风格同步图片接口顶层 usage.input_tokens、usage.output_tokens、usage.total_tokens
Gemini 原生 generateContentusageMetadata.promptTokenCount、usageMetadata.totalTokenCount
图片异步任务查询顶层 usage.prompt_tokens、usage.input_tokens、usage.output_tokens

如果失败未产生计费 usage,例如本地参数校验失败、额度不足、网络失败或上游未返回 usage,则不会附带 usage。

上游错误脱敏规则 ​

平台会保留排查所需的 request_id,但会对客户响应中的上游细节做安全处理。

不会直接返回给客户的内容包括:

  • 上游 API Key、账号、权限、余额、billing 或 quota 明细
  • 上游供应商 SDK、异常栈、内部 RequestID、URL 或网络传输细节
  • 内部渠道、分组、租户、组织或工作区名称
  • 原始 bad response status code、多级 request id 链或未清洗的上游 JSON

如果需要排查,请在工单中提供 error.request_id。平台支持团队可基于该 ID 查看内部链路和上游原始错误。

重试建议 ​

错误场景建议
内容安全或生图封控不建议直接重试,先修改 prompt、文本、图片或素材
请求参数、模型能力、上下文长度、图片尺寸不建议直接重试,先修正请求
上游限流 429延迟重试,并降低并发
上游超时或网络错误可以重试;长任务建议增加业务侧超时和幂等处理
上游 5xx 或坏响应可以短暂重试;持续出现请提交工单
upstream_channel_unavailable / upstream_capacity_unavailable可以稍后重试;持续出现请提交工单

TIP

生产环境建议记录 error.request_id、HTTP 状态码、error.code 和 error.type。不要仅依赖 message 做程序分支,因为多数上游业务错误会保留上游语义。

Fhddos AI 用户文档