# 故障排查

报错分两大类:**安装/环境类**(在你电脑上)和 **调用/网关类**(请求发出后)。下面按类型给出解法,网关类附了**真实高频报错对照表**。

> **通用技巧:** 看不懂的报错,截图发给能识别图片的 AI(豆包,或你已能用的 Claude / Codex),配一句"我是命令行新手,请一步一步带我解决,一次只给一步"。它会像远程陪你操作一样带你排查。

---

## 一、安装 / 环境类

## 1. 代理(翻墙)环境——最常见的隐形坑

很多电脑装了 Clash、V2Ray、Shadowsocks、机场客户端等代理软件。它们会悄悄改动系统网络设置,导致**浏览器能上网,但终端命令连不上**。

**典型症状:** `npm install` 卡住/超时、`ECONNREFUSED`、`ETIMEDOUT`、`UNABLE_TO_VERIFY_LEAF_SIGNATURE`、`CERT_HAS_EXPIRED`、`SELF_SIGNED_CERT_IN_CHAIN` 等证书/SSL 错误。

**解法:**
1. **完全退出**代理软件(右键退出,不是最小化)
2. **关掉当前终端,重开一个新窗口**(旧窗口的代理设置不会自动刷新)
3. 重新执行报错的命令

很多时候,关代理 + 重开终端就好了。

## 2. 命令找不到(command not found / 不是内部或外部命令)

刚装过却说找不到 `claude` / `codex` / `grok` / `node`:

- **没重开终端**:安装会改 `PATH`,先关掉重开新终端。
- **目录不在 PATH 里**:镜像安装的在 `~/.local/bin` 或 `~/.grok/bin`;npm 全局目录用 `npm bin -g` 查看,确认在 `PATH` 中。

## 3. 权限问题(Permission denied / EACCES)

多见于 `npm install -g`:macOS/Linux 命令前加 `sudo`;Windows 用**提升权限**的 PowerShell。不要随意 `chmod 777` 系统目录。

## 4. 网络 / 证书问题(timeout / fetch failed / SSL)

大概率仍是**代理**引起,先按第 1 节排查。确认无代理后,切国内 npm 源(见 [Node.js 环境](#/nodejs)):`npm config set registry https://registry.npmmirror.com`,或换个网络(手机热点)排除本地故障。

## 5. 版本不兼容 / engine 不满足

提示需要更高 Node 版本时,先看 `node -v`,按 [Node.js 环境](#/nodejs) 升级到最新 LTS。

---

## 二、调用 / 网关类(真实报错对照)

工具能连上、但请求出错。下面是平台上**最高频的真实报错**及处理方式。

## 先按这个顺序定位

工单或自查时,不要只发一句“报错了”。按下面顺序收集信息,能最快定位到是路径、分组、模型、请求体还是上游问题:

1. **请求 ID**:`x-request-id` / 响应头 `X-Request-Id` / 工具日志里的 request_id。没有它很难精确定位单次请求。
2. **用量错误详情**:控制台用量明细里的错误类型、错误来源、错误阶段、上游状态码、上游错误详情、是否有 `Recovered upstream error ...`。
3. **分组平台**:当前 API Key 属于 Claude、OpenAI 还是 Grok 分组;同一个端点在不同分组可能完全不同。
4. **Base URL**:是否带 `/v1`,有没有拼成 `/v1/v1/...`,是否用了线路域名。
5. **endpoint**:实际请求路径和方法,例如 `POST /v1/responses`、`GET /v1/responses`、`POST /v1/videos/generations`。
6. **model**:请求体里的 `model`、控制台分组开放模型、模型映射、用量里的上游真实模型。

最常见误判是把“模型列表里有”当成“该端点可用”。端点能力先看分组平台,模型名再看分组开放和映射。

### 为什么 request_id 仍要同时看用量与错误详情

`request_id` 是串联线索，但不同页面回答的问题不同：用量明细证明是否计费、用了哪个 Key/分组/模型、`request_type` 与 `billing_mode` 是什么；错误请求证明失败阶段、错误来源、上游状态和容灾链路。成功请求也可能有 `Recovered upstream error` 这类上游失败记录，它通常说明中间失败后已恢复，不等于最终失败。

错误详情里的用户侧 `category` 是稳定粗分类，适合工单和页面过滤：`auth`、`quota`、`rate_limit`、`invalid_request`、`upstream`、`service_unavailable`、`internal`、`cyber`、`other`。看到 `auth` 先查 Key 和权限，`quota` 先查余额/订阅/Key 限额，`rate_limit` 先降并发，`invalid_request` 先改请求体，`upstream` / `service_unavailable` 可稍后重试或换线路。

如果只有错误记录没有完整用量记录，也要提供错误 `id`、时间、模型、端点、Key 名称。响应头 `X-Request-Id` / `x-request-id` 和客户端自带的 `client_request_id` 都有排查价值；HTTP 200 但 SSE 里出现 `event: response.failed` 时，也应按流内失败提交。


## 先用最小 curl 定位协议

把下面的 Key 和模型名替换成控制台里当前分组实际可用值。哪个 curl 成功,说明该协议、Base URL、Key 和模型这一层先通了；失败时保留 HTTP status、响应体和 `x-request-id`。

Claude / Anthropic Messages:

```bash
curl https://api.clomio.ai/v1/messages \
  -H "Authorization: Bearer 你的Claude分组密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}'
```

Codex / OpenAI Responses:

```bash
curl https://api.clomio.ai/v1/responses \
  -H "Authorization: Bearer 你的OpenAI或Codex分组密钥" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-5.4","input":"ping","max_output_tokens":8}'
```

OpenAI Chat Completions:

```bash
curl https://api.clomio.ai/v1/chat/completions \
  -H "Authorization: Bearer 你的OpenAI分组密钥" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'
```

Grok Videos(Grok-only):

```bash
curl https://api.clomio.ai/v1/videos/generations \
  -H "Authorization: Bearer 你的Grok视频分组密钥" \
  -H "content-type: application/json" \
  -d '{"model":"控制台显示的视频模型ID","prompt":"one second test"}'
```

Gemini 原生:

```bash
curl https://api.clomio.ai/v1beta/models \
  -H "x-goog-api-key: 你的Gemini分组密钥"
```

Usage 查询:

```bash
curl 'https://api.clomio.ai/v1/usage?limit=5' \
  -H "Authorization: Bearer 你的密钥"
```

Claude Code 类问题先在会话里执行 `/status`，确认 `Anthropic base URL`、凭据来源和模型；不要只看 shell export 或某一个配置文件。如果 `/status` 仍显示旧 claude.ai 登录或旧网关,先 `/logout`,退出后清理旧变量:

```bash
env | grep -E 'ANTHROPIC|CLAUDE'
unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_BASE_URL="https://api.clomio.ai"
export ANTHROPIC_AUTH_TOKEN="你的密钥"
```

然后重开终端/Claude Code 再看 `/status`。Clomio 常规 Key 推荐 `ANTHROPIC_AUTH_TOKEN`，对应 `Authorization: Bearer`;`ANTHROPIC_API_KEY` 对应 `x-api-key`,只在网关明确要求时使用。

## 端点 × 分组速查

| 端点 | Claude 分组 | OpenAI 分组 | Grok 分组 |
|------|:----:|:----:|:----:|
| `/v1/messages` | ✓ | ✓* | ✗ |
| `/v1/messages/count_tokens` | ✓ | ✗ | ✗ |
| `/v1/chat/completions` | ✓** | ✓ | ✗ |
| `POST /v1/responses` | ✗ | ✓ | ✓ |
| `GET /v1/responses` | ✗ | ✓ | ✗ |
| `/v1/embeddings` | ✗ | ✓ | ✗ |
| `/v1/images/*` | ✗ | ✓ | ✓ |
| `/v1/videos/*` | ✗ | ✗ | ✓ |
| `/v1/web_search` | ✗ | ✗ | ✓ |
| `/v1/models` | ✓ | ✓ | ✓ |

> \* OpenAI 分组只有在当前分组开放 Messages 兼容能力时才接受 `/v1/messages`,否则会返回 `This group does not allow /v1/messages dispatch`。
>
> \** Claude 分组的 Chat Completions 是转换兼容路径;Claude Code only 分组仍只允许 `/v1/messages`。

当前没有 `GET /v1/responses/{id}` 和 `GET /v1/models/{id}`。`GET /v1/responses` 是 Codex/Responses WebSocket v2 入口,不是查询历史响应的 REST 资源。

常见误写也包括 `/openai/v1/...`、`/v1/images2api/*`、`/v1/images/variations`、`GET /v1/web_search`、`POST /v1/videos/{id}` 和 `/antigravity/v1/responses`。这些不是当前公开 gateway 路由；按 [API 概述](#/api-usage) 的端点表换成已注册路径。

配置入口可直接跳到对应文档:Claude 看 [Claude Code](#/claude-code),Codex 看 [Codex](#/codex),Grok 看 [Grok](#/grok),Cherry Studio 看 [Cherry Studio](#/cherry-studio),多供应商切换看 [CC Switch](#/cc-switch)。

## 配置类(最常见,你能自己解决)

| 报错文案(关键词) | 含义 | 怎么办 |
|------|------|--------|
| `The current group does not support the requested model "xxx". Available models: ...` | **分组明确不支持该模型**。OpenAI/Claude 兼容响应通常是 403 `permission_error`;Gemini 原生路径会更像 `PERMISSION_DENIED`;可用模型列表过长时只展示前 20 个并显示 `and N more` | 把模型名改成报错里 `Available models` 列出的;或在控制台给密钥换一个支持该模型的分组 |
| `model_not_found` / `Model "xxx" is not supported by any configured account in this group` | 当前分组无法服务该模型。常见于模型名写错、模型映射未开放或用错分组 | 先核对模型名；再看控制台该分组支持模型。工单请带 `model_not_found`、模型名、分组名 |
| `This group does not allow /v1/messages dispatch` | OpenAI 分组未开放 Claude Messages 形状转 OpenAI 调度 | 改用 `/v1/responses` / `/v1/chat/completions`；或换到已开放 Messages 兼容能力的 OpenAI 分组 |
| `This group is restricted to Claude Code clients (/v1/messages only)` | Claude Code 专用分组被拿去调用 OpenAI Chat/Responses 端点 | Claude Code 用 `/v1/messages`;Codex/OpenAI SDK 请换 GPT/OpenAI 分组 |
| `Chat Completions API is not supported for this platform` / `Messages API is not supported for this platform` / `Responses WebSocket API is not supported for this platform` | 当前分组未开放对应协议 | Grok/OpenAI 分组通常可用 Chat/Responses，Messages 和 WS 需看分组能力；Embeddings 仍使用 OpenAI 分组 |
| `api_key_in_query_deprecated` / `API key in query parameter is deprecated` | OpenAI-compatible/Claude 网关路径把 API Key 放在 query 参数里 | 改用 `Authorization: Bearer sk-...`；Gemini 原生路径如需 query 只使用 `key=`，不要用 `api_key=` |
| `ACCESS_DENIED` / `Access denied. Your IP is ...` | API Key 绑定了 IP 白名单或访问规则,当前出口 IP 不在允许范围 | 在控制台更新 Key 的 IP 白名单,或固定代理出口后重试 |
| `Token counting is not supported for this platform` | Claude Code 会额外请求 `/v1/messages/count_tokens` 做上下文估算；OpenAI/Grok 分组或不支持该能力的上游会返回 404 | 只要主对话 `POST /v1/messages` 正常，通常可忽略；主对话也失败时再检查分组是否支持 Messages |
| `Embeddings API is not supported for this platform` | `/v1/embeddings` 只支持 OpenAI 分组 | 换 OpenAI 分组和 embedding 模型 |
| `Images API is not supported for this platform` | `/v1/images/*` 只支持 OpenAI/Grok 分组 | 换 OpenAI 或 Grok 图像分组 |
| `Web Search API is not supported for this platform` | `/v1/web_search` 只支持 Grok 分组 | 换 Grok 分组 |
| `Videos API is not supported for this platform` | 视频端点只在 Grok 视频分组开放,OpenAI/Claude 等分组会拒绝 | 视频生成请使用 Grok 分组;文本/图片继续用各自分组 |
| `API key group platform is not gemini` | `/v1beta` Gemini 原生路径使用了非 Gemini 分组 | 换 Gemini 分组 Key;Antigravity 客户端用 `/antigravity/v1beta/...` |
| `Query parameter api_key is deprecated. Use Authorization header or key instead.` | Gemini 风格入口用了废弃 `api_key` query | 改用 `Authorization: Bearer`、`x-goog-api-key` 或 `key` query |
| `Video generation is not enabled for this group` | 当前分组没有开启视频生成权限 | 换到已开通视频的 Grok 分组,或联系支持开通 |
| `Your input exceeds the context window of this model` | **输入超出该模型上下文窗口** | 精简输入;用 `/compact` 压缩对话;或换更大窗口的模型 |
| `Insufficient account balance` / `余额不足` | **额度用尽** | 控制台充值,见 [计费与额度](#/billing) |
| `API Key 所属分组已停用` | 该密钥的**分组被停用** | 换一个可用分组重建密钥 |
| `No active subscription found for this group` | 该分组**无有效套餐/订阅** | 在控制台为该分组开通/续订,或换分组 |
| `daily usage limit exceeded` / `weekly usage limit exceeded` / `monthly usage limit exceeded` | 密钥或订阅触发日/周/月用量限制 | 等窗口重置;或在控制台调整限额/换分组 |
| `rate limit exceeded` | 本平台 API Key 侧限速,还没到上游 | 降低并发和自动重试频率;工单带 API Key 名称和时间窗口 |
| `内容审计命中风险规则，请调整输入后重试` | **内容审计**拦截 | 调整输入措辞后重试。若认为误判,工单带 request_id 和原始提示词摘要 |
| `内容审计服务暂不可用，请稍后重试` | 内容审计服务异常且当前策略按失败拦截 | 稍后重试;持续出现提交工单,带 `CONTENT_MODERATION` / `audit_api_failed` 关键词 |
| `Request body too large, limit is ...` / `Request body is too large` / `message too big` | **请求体过大**(HTTP 413),通常是附件、图片、长上下文或整仓内容太大 | 减少附件/上下文;长文件分批处理;避免把二进制/大日志直接塞进一条请求 |

## 服务波动类(多为临时,重试或换线路)

| 报错文案(关键词) | 含义 | 怎么办 |
|------|------|--------|
| `No available accounts supporting model: xxx` | 当前没有可用服务能力支持该模型；不一定是真模型名错误，也可能是临时容量或上游限速 | 先看是否同时出现 `model_not_found`（配置问题）；没有则按临时容量问题处理：稍后重试、换线路/分组/模型；工单带 request_id、模型名和时间 |
| `No available accounts` / `Service temporarily unavailable` | 当前分组暂时没有可用服务能力。常见原因：上游 429、服务额度/订阅限制、临时限制或并发槽位耗尽 | 稍后重试；换[网关线路](#/gateway-lines)或分组。工单请带 request_id、时间和错误体 |
| `No available compatible accounts for video generation` | 视频请求暂时没有可用的视频生成服务能力 | 确认使用 Grok 视频分组；稍后重试或换分组 |
| `temp_unschedulable` / `temp_unschedulable_until` / `temporary unschedulable` | 服务能力被临时冷却；`temp_unschedulable_until` 是恢复时间，`temp_unschedulable_reason` 是冷却原因。它不是用户余额或 Key 额度能清掉的问题 | 等冷却时间结束会自动恢复；持续出现需工单带 request_id、分组和关键词 `temp_unschedulable_reason` |
| `Upstream transport error` / `Upstream service temporarily unavailable` / `Upstream request failed` | **上游临时不可用**或网络传输失败 | 稍等重试;换线路。若多次自动切换后仍失败,带 request_id 工单 |
| `Too many pending requests, please retry later` | **请求堆积/并发槽位等待超时** | 降低并发,稍后重试;避免多个工具共用同一密钥高并发冲刺 |
| `Concurrency limit exceeded for user/account` | 用户级或服务侧并发槽位已满，不是上游模型不存在 | 降低并发、等待当前流式任务结束；不要让多个客户端共用同一 Key 同时冲刺 |
| `Upstream rate limit exceeded, please retry later` / `rate_limit_exceeded` | 上游限速,网关会尽量切换账号;全部账号都受限时返回 429 | 降并发,稍后重试;换分组/线路分流 |
| `The usage limit has been reached` / `You've hit your usage limit` / `usage_limit_reached` / `Approaching upstream rate limits` | 上游用量上限或 Codex/ChatGPT 套餐限制 | 等上游重置；换分组/模型；高峰期不要持续重试同一任务 |
| `Upstream access forbidden` | 上游拒绝访问 | 换线路重试;持续出现联系支持 |
| `our servers are currently overloaded` | 上游过载 | 稍后重试,或换线路 |

快速区分本地限制 vs 上游限制：`Too many pending requests...`、`Concurrency limit exceeded...` 多数是排队/并发槽位；`Upstream rate limit exceeded...`、`rate_limit_exceeded`、`The usage limit has been reached` 更偏上游限速或套餐。`Recovered upstream error 429/5xx: ...` 表示中途某个上游失败被容灾覆盖，不等于最终请求一定失败；最终状态仍看客户端响应和用量/错误详情。


## OpenAI Responses / Codex 续接类

这类多见于 Codex、OpenAI Responses API、带工具调用的多轮会话。它们通常不是网络问题,而是**续接上下文或请求结构**不被上游接受。

| 报错文案(关键词) | 含义 | 怎么办 |
|------|------|--------|
| `invalid_encrypted_content` / `The encrypted content could not be verified` | 上一轮返回的加密 reasoning/context 无法被当前上游验证。常见于 `previous_response_id` 续接、账号切换、会话太旧或上下文被工具改写 | 新开一轮对话或执行 `/compact`;不要手工拼接/复用旧 `encrypted_content`。工单带 request_id、`previous_response_id`、是否 Codex |
| `previous_response_not_found` / `unsupported_previous_response_id` | 上游找不到或不支持你要续接的 response id | 新开会话或让工具压缩上下文后继续;不要跨分组/跨工具复用 response id |
| `function_call_output requires call_id on HTTP requests` | 发送了工具调用结果,但缺少对应 `call_id` | 使用工具/SDK自动生成的工具结果,不要手写删字段;HTTP 普通请求必须带 `call_id` |
| `function_call_output requires item_reference ids matching each call_id` | 工具结果虽然有 `call_id`,但缺少能关联原始工具调用 item 的 reference | 让 Codex/SDK接管工具调用续接;不要只保存最后一条 `function_call_output` 后重放 |
| SSE 中出现 `event: response.failed` | SSE 已经开始后才发生错误,HTTP 状态码可能仍是 200,真实失败在 SSE 终止事件里 | 看 `response.error.code/message`;工单带完整 SSE 末尾片段和 request_id |
| SSE 中出现 `event: response.cancelled` | 同一会话有新请求抢占、客户端主动取消,或网关按 Responses 协议发出取消终止事件 | 如果是自己开了新请求,旧流取消属正常;否则带 request_id 和工具日志排查 |

## Base URL / 端点 / 分组不匹配

| 现象 | 常见原因 | 正确做法 |
|------|----------|----------|
| `404 Not Found`、`Cannot POST /v1/v1/...`、路径里出现两个 `/v1` | Base URL 多填了 `/v1`,而工具自己又追加 `/v1` | 若工具有独立 Endpoint Path,Base URL 填 `https://api.clomio.ai`;若工具要求 OpenAI Base URL,通常填 `https://api.clomio.ai/v1`。不要同时在两个地方都写 `/v1` |
| `404` 且路径没有 `/v1` | 工具要求 OpenAI-compatible 地址,但 Base URL 少了 `/v1` | 把 Base URL 改为 `https://api.clomio.ai/v1`、`https://sub.qazwc.com/v1` 或 `https://crs.qazwc.com/v1` |
| Claude Code 报 `/v1/messages` 相关错误 | Claude Code 应走 Anthropic Messages 协议 | Claude Code 用 Claude 分组和 `/v1/messages`;不要用 GPT/Grok 分组 |
| Codex / OpenAI SDK 报 `/v1/responses`、`/v1/chat/completions` 相关错误 | OpenAI 工具应走 OpenAI-compatible 协议 | Codex/OpenAI SDK 用 GPT/OpenAI 分组;不要用 Claude-only 分组 |
| Grok 视频请求在 OpenAI/Claude 分组返回 `Videos API is not supported for this platform` | 视频路由按分组平台限制,Grok 视频是 Grok/xAI 能力 | 视频用 Grok 分组;文本、图片、Claude Code 分开建 Key |
| `GET /v1/responses/{id}` 或 `GET /v1/models/{id}` 返回 404 | 当前网关没有这两个按 ID 查询的 REST 路由。`GET /v1/responses` 仅是 Codex/Responses WS v2 流入口;Models 只支持列表 | Responses 多轮用下一次 `POST /v1/responses` 携带 `previous_response_id`;查模型用 `GET /v1/models` 列表或发最小请求验证 |

## 控制台账号 / 支付 / 工单真实报错

这些错误来自控制台网页功能,不要和模型网关调用失败混为一谈:

| 错误关键词 | 来源 | 处理 |
|---|---|---|
| `PENDING_AUTH_NOT_READY` / `PENDING_AUTH_TARGET_USER_MISMATCH` / `Pending oauth session provider mismatch` | OAuth pending 注册/绑定 | 重新从对应 provider 入口授权,不要混用旧链接;详见 [邀请、工单与账号](#/console-account) |
| `TOTP_INVALID_CODE` / `TOTP_SETUP_EXPIRED` / `TOTP_TOO_MANY_ATTEMPTS` | TOTP 双因素认证 | 核对手机时间,过期则重新 setup,多次失败先等冷却 |
| `GROUP_NOT_ALLOWED` | API Key 创建/编辑绑定分组 | 当前用户不能绑定该分组：订阅型分组需有效订阅，其他分组以控制台可选列表为准；换可用分组或提交工单 |
| `API_KEY_EXISTS` / `API_KEY_TOO_SHORT` / `API_KEY_INVALID_CHARS` / `API_KEY_RATE_LIMITED` / `INVALID_IP_PATTERN` | API Key 创建、导入、编辑 IP 白名单 | Key 已存在、长度不足、字符非法、失败次数过多或 IP/CIDR 格式错误;换更长 Key、只用字母数字下划线连字符,按 CIDR 修正白名单 |
| `API_KEY_REQUIRED` / `INVALID_API_KEY` | API Key 缺失、填错或用了错误 header | 使用 `Authorization: Bearer sk-...`;确认没有把 Key 放到 query,也没有多余空格/换行 |
| `API_KEY_INACTIVE` / `API_KEY_DISABLED` / `API_KEY_EXPIRED` / `API_KEY_QUOTA_EXHAUSTED` / `API_KEY_RATE_5H_EXCEEDED` / `API_KEY_RATE_1D_EXCEEDED` / `API_KEY_RATE_7D_EXCEEDED` | API Key 网关鉴权/额度 | Key 被停用、过期、总额度或 5h/1d/7d 窗口用完;启用/续期/调额度或等待窗口重置 |
| `GROUP_DELETED` / `GROUP_DISABLED` | Key 绑定的分组已删除或停用 | 给 Key 换可用分组;订阅型分组先确认套餐仍有效 |
| `REGISTRATION_DISABLED` / `EMAIL_EXISTS` / `EMAIL_RESERVED` / `EMAIL_VERIFY_REQUIRED` / `INVALID_VERIFY_CODE` / `INVALID_CREDENTIALS` / `USER_NOT_ACTIVE` / `TOKEN_EXPIRED` / `INVALID_TOKEN` / `TOKEN_REVOKED` / `REFRESH_TOKEN_INVALID` / `REFRESH_TOKEN_EXPIRED` / `REFRESH_TOKEN_REUSED` | 注册、登录、OAuth 绑定或控制台会话 | 注册关闭、邮箱已存在/保留、验证码缺失或错误、密码错误、账号禁用、登录态过期或 token 被撤销;按提示重新验证/登录,账号禁用需联系支持 |
| `PAYMENT_METHOD_DISABLED` / `BALANCE_PAYMENT_DISABLED` / `PAYMENT_DISABLED` / `INVALID_AMOUNT` / `INVALID_INPUT` / `TOO_MANY_PENDING` / `DAILY_LIMIT_EXCEEDED` / `PAYMENT_GATEWAY_ERROR` / `NO_AVAILABLE_INSTANCE` | 支付创建或通道选择 | 支付方式关闭、金额/套餐参数非法、未支付订单过多、当日限额或通道不可用;按页面范围重新下单,必要时换支付方式 |
| `INVALID_RETURN_URL` / `PAYMENT_RESUME_NOT_CONFIGURED` / `INVALID_RESUME_TOKEN` / `INVALID_WECHAT_PAYMENT_RESUME_TOKEN` / `INVALID_OUT_TRADE_NO` | 支付/订单恢复 | 恢复链接可能过期、签名不匹配或订单不匹配;`out_trade_no` 为空/过长/含非法字符也会失败。回到订单页恢复/重新下单;带订单 ID、`out_trade_no` 提工单 |
| `CANCEL_RATE_LIMITED` / `ORDER_ALREADY_PAID` / `INVALID_STATUS` | 取消订单 | 只允许取消 `PENDING` 订单;若上游已支付会拒绝取消;频繁取消先等冷却 |
| `INVOICE_ORDER_IDS_REQUIRED` / `INVOICE_ORDER_INELIGIBLE` / `INVOICE_ALREADY_INVOICED` / `INVOICE_CANNOT_CANCEL` / `INVOICE_NOT_ISSUED` / `INVOICE_FILE_STORAGE_UNAVAILABLE` | 退款/发票 | 先看订单是否可开票、发票状态和可退金额;不要重复提交退款或上传空文件 |
| `TICKET_REVISION_CONFLICT` / `TICKET_REVISION_REQUIRED` / `TICKET_NOT_EDITABLE` | 工单编辑/提交 | 刷新工单详情,基于最新 revision 重新编辑 |
| `TICKET_MESSAGE_REQUIRED` / `TICKET_MESSAGE_TOO_LARGE` / `MEDIA_STORAGE_DISABLED` | 工单回复/附件 | 填正文、压缩附件或等待媒体服务恢复 |
| `VERIFY_CODE_TOO_FREQUENT` / `VERIFY_CODE_MAX_ATTEMPTS` / `NOTIFY_CODE_USER_RATE_LIMIT` | 通知邮箱验证码 | 等冷却后再发;验证码 15 分钟有效,最多 5 次尝试 |
| `TOO_MANY_NOTIFY_EMAILS` / `EMAIL_NOT_FOUND` | 通知邮箱管理 | 额外通知邮箱最多 3 个;删除/切换前确认邮箱存在 |
| `MEDIA_FILE_REQUIRED` / `MEDIA_FILE_TOO_LARGE` / `MEDIA_SIGNATURE_EXPIRED` / `MEDIA_FORBIDDEN` / `MEDIA_NOT_FOUND` | 媒体/附件上传或下载 | 重新上传、缩小文件或刷新签名链接;不要把媒体接口当模型文件 API |
| `REFRESH_TOKEN_INVALID` / `REFRESH_TOKEN_EXPIRED` / `REFRESH_TOKEN_REUSED` / `invalid refresh token` | 控制台会话刷新失败、过期或 refresh token 被复用疑似重放 | 退出后重新登录;如已点“退出所有设备”,所有设备都需要重新登录 |
| `PASSWORD_RESET_DISABLED` / `EMAIL_SUFFIX_NOT_ALLOWED` | 账号注册/重置密码被系统设置限制 | 使用允许的邮箱后缀;重置密码入口关闭时联系支持 |
| `CHANNEL_MONITOR_NOT_FOUND` | 渠道监控详情 | 可能是功能关闭或该渠道不可见,先看列表是否为空 |
| `AI_STUDIO_DISABLED` | 控制台 AI Studio | 站点关闭或入口未开放,详见 [AI Studio](#/console-ai-studio) |
| `AI_KEY_NOT_FOUND` / `AI_KEY_FORBIDDEN` / `AI_KEY_GROUP_INVALID` / `AI_LINE_MISMATCH` | AI Studio/技能运行时选择的 Key、线路或分组不匹配 | 重新选择属于当前用户、已绑定有效分组且属于该线路的 API Key |
| `AI_SKILL_NOT_FOUND` / `AI_SKILL_VERSION_NOT_FOUND` / `AI_SKILL_ACCESS_DENIED` | 技能市场访问 | 技能/版本不存在、未发布或无权访问;刷新市场/已安装列表,确认当前账号和技能可见性 |
| `AI_SKILL_INPUT_REQUIRED` / `AI_SKILL_NAME_REQUIRED` / `AI_SKILL_TYPE_INVALID` / `AI_SKILL_RUN_INPUT_REQUIRED` / `AI_SKILL_RUN_MODE_INVALID` | 技能创建或运行输入非法 | 补齐名称、类型、变量和运行模式;不要手改接口参数 |
| `AI_SKILL_VERSION_NOT_APPROVED` / `AI_SKILL_SCRIPT_CREATION_UNSUPPORTED` / `AI_SKILL_SCRIPT_EXECUTION_UNAVAILABLE` / `AI_SKILL_SCRIPT_NOT_APPROVED` / `AI_SKILL_SCRIPT_ARTIFACT_MISMATCH` / `AI_SKILL_EXECUTION_SPEC_INVALID` / `AI_SKILL_SERVICE_UNAVAILABLE` / `AI_SKILL_BALANCE_UNAVAILABLE` / `AI_SKILL_EXECUTION_FAILED` | 技能市场 | 版本需审核通过;脚本技能普通用户暂不可创建或执行产物不匹配;余额/执行服务异常时保留 run id 和版本 id,见 [技能市场与创作者中心](#/console-skills) |

## 关于 `Recovered upstream error ...`

如果你在使用记录里看到 **"Recovered upstream error 5xx/429: ..."** 而请求其实**成功了**(状态 200),这是**好事**——说明网关检测到某个上游出错后,自动切换账号/重试并成功了。**无需处理**,这正是多账号容灾在起作用。
这类记录通常来自上游错误关联链路：先按 `request_id` 查最终用量/响应，再看 ops 里同一 `request_id` 或 `client_request_id` 附近的 upstream 记录。若最终请求失败，工单请同时带最终错误和 recovered/upstream 错误摘要；若最终成功，只在频繁出现、耗时异常或扣费异常时继续排查。


---

## 三、HTTP 错误码速查

| 码 | 含义 | 优先处理 |
|----|------|----------|
| `200` | 成功(若带 "Recovered" 说明自动容灾成功,正常) | — |
| `400` | 参数错误 / 超出上下文 | 检查请求体、模型名;精简输入 |
| `401` / `403` | 鉴权失败 / 分组不支持 / 余额不足 | 见上"配置类" |
| `404` | 地址错误 / 端点不属于该分组 | 检查 `/v1` 路径;核对[端点 × 分组](#/api-usage) |
| `413` | 请求体过大 | 减少附件 / 上下文 |
| `429` | 触发限速 | 降并发、稍后重试、换分组/线路 |
| `502` / `503` | 上游临时不可用 / 无可用账号 | 重试,或换[网关线路](#/gateway-lines) |
| `524` / `525` | 网关超时 / TLS 握手问题 | 重试;换线路 |

---

## 四、排查口诀

| 症状关键词 | 先查 |
|-----------|------|
| timeout / ECONNREFUSED / SSL / 证书 | 代理环境(一·1) |
| command not found / 不是内部命令 | 重开终端、PATH(一·2) |
| Permission denied / EACCES | 权限,加 sudo / 提升权限(一·3) |
| does not support the requested model | 分组与模型不匹配(二·配置类) |
| exceeds the context window | 输入太长,精简/压缩/换大窗口模型 |
| No available accounts / Upstream error | 上游波动,重试或换线路(二·服务波动类) |
| 余额不足 / Insufficient balance | 充值([计费与额度](#/billing)) |
| 429 / usage limit | 限速,降并发或换分组 |

---

> 还搞不定?带上**完整报错截图**和你的密钥**分组名**,在控制台 [api.clomio.ai](https://api.clomio.ai) 提交[工单](#/console)联系支持。