错误响应汇总

# 错误响应汇总

本文汇总客户端可见的错误响应、提示文案及处理建议。

## 1. 错误响应格式

OpenAI、Responses、Anthropic 入口及模型、账户、用量、任务查询等接口，使用统一错误输出时返回：

```json
{
  "error": {
    "message": "invalid api key",
    "type": "ee_proxy_error",
    "code": "invalid_api_key"
  },
  "request_id": "ee-ai-proxy-..."
}
```

| 字段            | 说明                                                         |
| --------------- | ------------------------------------------------------------ |
| HTTP 状态码     | 本次接口响应的 HTTP 状态                                     |
| `error.code`    | 字符串错误码，用于调用方判断错误类型                         |
| `error.message` | 用户可见提示，可能包含动态内容，不建议按完整文案匹配         |
| `error.type`    | 默认为 `ee_proxy_error`；渠道错误使用 `source_channel_error` |
| `request_id`    | 与响应头 `X-EE-Response-ID` 一致，存在时写入正文；反馈问题时请提供此值 |

以下表格中的 `{model}`、`{protocol}` 分别表示实际模型名和协议名。未单独列出 `error.type` 的表格均使用 `ee_proxy_error`。

## 2. 用户端错误码

### 2.1 请求参数与调用方式

| HTTP 状态码 | `error.code`            | `error.message`                                              | 含义与处理                                                  |
| ----------- | ----------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
| 400         | `invalid_request`       | 具体参数解析或请求规范化错误                                 | 检查请求体、模型字段和参数格式                              |
| 400         | `invalid_async_mode`    | `X-EEProxy-Async must be true or false`                      | 任务接口的异步模式请求头无效，使用单个 `true` 或 `false` 值 |
| 400         | `unsupported_sync_mode` | `synchronous mode is currently supported only for image generation` | 请求了暂不支持的同步媒体模式，改用异步模式                  |
| 400         | `unsupported_protocol`  | `unsupported relay protocol "{protocol}"`                    | 不支持该入口协议                                            |
| 405         | `method_not_allowed`    | `method not allowed`                                         | 代理入口 HTTP 方法错误                                      |

### 2.2 身份认证与权限

| HTTP 状态码 | `error.code`              | `error.message`                                              | 含义与处理                                                   |
| ----------- | ------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 401         | `invalid_api_key`         | `api-key is missing` 或 `invalid api key`                    | 凭证缺失或无效，检查 API Key                                 |
| 403         | `ip_not_allowed`          | `client IP is not allowed for this api key`                  | 当前 IP 不在 API Key 白名单内，检查白名单配置                |
| 403         | `model_not_allowed`       | `model "{model}" is not allowed for this api key` 或 `model "{model}" is not enabled for this workspace` | API Key 无模型权限，或工作空间未启用模型，联系管理员调整授权 |
| 403         | `workspace_not_available` | `workspace is not available`                                 | 工作空间不可用，联系管理员检查配置                           |
| 404         | `model_not_found`         | `model "{model}" not found`                                  | 模型不存在或无法解析，检查模型名称；模型名为空时返回 `model "" not found` |

### 2.3 钱包、额度与限流

| HTTP 状态码 | `error.code`                    | `error.message`                                              | 含义与处理                                               |
| ----------- | ------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------- |
| 400         | `workspace_wallet_not_exit`     | 工作空间未开通【ai-hub】账户或钱包，请联系管理员开通。       | 联系管理员开通账户或钱包                                 |
| 402         | `insufficient_balance`          | ⚠️ 空间账户余额不足，请及时充值后重试。                       | 余额不足以完成预扣，充值后重试                           |
| 402         | `balance_below_threshold`       | ⚠️ 空间账户余额不足，请及时充值后重试。                       | 余额低于最低阈值，充值后重试                             |
| 429         | `api_key_amount_quota_exceeded` | `api key amount quota exceeded`                              | API Key 金额额度耗尽，调整额度或等待重置                 |
| 429         | `api_key_token_quota_exceeded`  | `api key token quota exceeded`                               | API Key Token 额度耗尽，调整额度或等待重置               |
| 429         | `monthly_money_quota_exceeded`  | ⚠️ 本月配额已用尽，请联系空间管理员调整配额或等待次月自动重置。 | 月金额额度耗尽，调整额度或等待次月重置                   |
| 429         | `monthly_token_quota_exceeded`  | ⚠️ 本月配额已用尽，请联系空间管理员调整配额或等待次月自动重置。 | 月 Token 额度耗尽，调整额度或等待次月重置                |
| 429         | `workspace_rpm_rate_limited`    | `workspace rpm quota exceeded`                               | 工作空间每分钟请求数达到限制，降低请求速率               |
| 429         | `workspace_tpm_rate_limited`    | `workspace tpm quota exceeded`                               | 工作空间每分钟 Token 用量达到限制，降低 Token 用量或并发 |

### 2.4 渠道与服务错误

| HTTP 状态码 | `error.code`               | `error.type`           | `error.message`                                              | 含义与处理                                                   |
| ----------- | -------------------------- | ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 500         | `internal_error`           | `ee_proxy_error`       | `channel invocation error`                                   | 未分类内部错误，提供 `request_id` 联系服务方                 |
| 503         | `no_channel`               | `ee_proxy_error`       | `no available channel for model` 或 `channel for model "{model}" does not support protocol "{protocol}"` | 没有满足模型、协议、额度等条件的可用渠道，联系管理员检查渠道 |
| 503         | `service_draining`         | `ee_proxy_error`       | `service is draining`                                        | 当前实例正在排空，稍后重试或切换健康实例                     |
| 503         | `channel_invocation_error` | `source_channel_error` | `channel invocation error`                                   | 已选定渠道后发生普通调用异常，如网络或请求准备失败           |
| 503         | `upstream_error`           | `source_channel_error` | `channel invocation error`                                   | 上游响应异常                                                 |

### 2.5 异步任务接口错误

| HTTP 状态码 | `error.code`             | `error.message`                                | 含义与处理                                          |
| ----------- | ------------------------ | ---------------------------------------------- | --------------------------------------------------- |
| 403         | `async_task_not_allowed` | `async task is not accessible by this api key` | 当前 API Key 无权查询该任务，使用提交任务的 API Key |
| 404         | `async_task_not_found`   | `async task not found`                         | 任务不存在或任务 ID 格式无效，检查任务 ID           |

任务提交和查询还可能返回上述鉴权错误或 `internal_error`。查询成功后，仍需检查任务执行结果，见第 3 节。

## 3. 异步任务失败结果

`GET /v1/tasks/{task_id}` 返回 HTTP 200 表示查询成功，任务本身仍可能失败。客户端还需检查 `output.task_status` 和任务错误字段。

代理任务轮询超时的结果示例（任务正文还可能包含任务 ID 等字段）：

```json
{
  "output": {
    "task_status": "UNKNOWN",
    "code": "async_task_timeout",
    "message": "async task exceeded its query deadline"
  }
}
```

此处 `output.code: async_task_timeout` 表示任务轮询超时，`output.task_status` 为 `UNKNOWN`；查询接口仍返回 HTTP 200。

其他任务失败的错误码和提示由供应商定义，可能位于 `output.code`、`output.message` 或顶层 `code`、`message`，以实际任务响应为准。