错误响应结构
平台 API 失败时会返回错误对象。不同兼容协议可能会保持对应协议的外层形态，但核心字段语义一致。
{
"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 | 视为运营供给问题，统一包装为上游渠道或容量暂不可用 |
| 清洗后仍无法安全表达的内部泄漏 | 使用平台安全文案包装，不直接展示原始上游错误 |
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.type | error.code | 含义 | 建议处理 |
|---|
system_error | upstream_channel_unavailable | 上游渠道账号、Key、权限、账号状态暂不可用 | 稍后重试；持续出现请提交工单 |
system_error | upstream_capacity_unavailable | 上游渠道余额、billing、quota、容量或供给暂不可用 | 稍后重试；持续出现请提交工单 |
内容安全与生图封控
当上游明确返回内容安全或生图封控原因时，平台会尽量保留客户可理解的语义，让客户知道需要修改输入内容。
平台不会直接暴露上游内部字段，例如：
| 上游内部信号 | 客户可见处理 |
|---|
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 原生 generateContent | usageMetadata.promptTokenCount、usageMetadata.totalTokenCount |
| 图片异步任务查询 | 顶层 usage.prompt_tokens、usage.input_tokens、usage.output_tokens |
上游错误脱敏规则
平台会保留排查所需的 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 | 可以稍后重试；持续出现请提交工单 |
生产环境建议记录 error.request_id、HTTP 状态码、error.code 和 error.type。不要仅依赖 message 做程序分支，因为多数上游业务错误会保留上游语义。
