> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phanedge.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误码与响应说明

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

## 错误响应结构

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

```json theme={null}
{
  "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`。
</Info>

## 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、容量或供给暂不可用 | 稍后重试；持续出现请提交工单 |

其他上游业务错误，例如内容安全、限流、超时、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 原生 `generateContent` | `usageMetadata.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` 做程序分支，因为多数上游业务错误会保留上游语义。
</Tip>