常见报错速查

先做三步定位

不要一上来就改客户端配置。 按这个顺序，能在两分钟内确定问题出在哪一层：

1. 打基线端点（OpenAI Chat）

   curl -i https://api.ziai.lol/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -d '{"model":"模型ID","messages":[{"role":"user","content":"你好"}]}'

   • 不通 → 问题在账号层：密钥、额度、分组、IP 白名单、模型 ID。与客户端无关，别去改客户端。
   • 通了 → 进入第 2 步。

2. 打客户端实际使用的那个协议端点

   Claude Code 用户打 /v1/messages，Codex 用户打 /v1/responses：

   # Anthropic Messages
   curl -i https://api.ziai.lol/v1/messages \
     -H "content-type: application/json" \
     -H "x-api-key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "anthropic-version: 2023-06-01" \
     -d '{"model":"模型ID","max_tokens":64,"messages":[{"role":"user","content":"你好"}]}'

   # OpenAI Responses
   curl -i https://api.ziai.lol/v1/responses \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -d '{"model":"模型ID","input":"你好"}'

   • 基线通、这个不通 → 问题在协议层：该模型在 ZiAI 上没有这个协议的通道。见协议不匹配详解。
   • 两个都通 → 进入第 3 步。

3. 回到客户端

   此时 ZiAI 侧完全正常，问题 100% 在客户端配置：地址层级（/v1 多加或少加）、密钥变量名、模型 ID 拼写、启用开关没打开。 对照配置速查表逐字段核对。

加上 -i 看响应头

curl -i 会打印状态行与响应头。Retry-After（限速）、x-request-id（找站长排查时提供）、 以及真实的 HTTP 状态码都在这里 —— 很多客户端只给你一句模糊的错误文案。

按报错码查

401 Unauthorized

优先排查	说明
Claude Code 用错了密钥变量	ANTHROPIC_API_KEY 发 x-api-key，ANTHROPIC_AUTH_TOKEN 发 Authorization: Bearer。接中转站请用后者。报错不会提示这个原因
密钥复制不完整	首尾多空格、少字符、带了引号
密钥被禁用或已过期	到控制台确认状态
密钥设了 IP 白名单	你的出口 IP 不在名单内（公司网络、代理、手机热点都会变）
Codex 密钥位置不对	Codex ≥ 0.149 不再从 auth.json 继承环境凭据；改用 env_key 或升级 CC-Switch ≥ v3.20.1

403 Forbidden

• 密钥的模型限制里没有你要调用的模型 → 编辑密钥放开限制，或换模型
• 密钥所属分组无权访问该渠道 → 见计费、配额与限速
• 站点级访问控制（地区、UA 限制）→ 联系站长

404 Not Found

最高频错误，两种成因相反：

成因	实际请求变成	修法
多加了 /v1	/v1/v1/chat/completions	去掉一层 /v1
少加了 /v1	/chat/completions	补上 /v1

各客户端的正确形态见配置速查表。特别注意：

• Claude Code 的 ANTHROPIC_BASE_URL → 不带 /v1
• CherryStudio 自定义 OpenAI 兼容服务商 → 填到 /v1 层级
• ChatBox → 主机填根地址 + API 路径留空；或主机带 /v1 + 路径填 /chat/completions
• Codex / ZCode(OpenAI) / WorkBuddy → 带 /v1

其他 404 原因：

• 把控制台地址当成了 API 地址（控制台是网页，不是端点）
• Codex 尝试 WebSocket 传输：报错含 wss:// → provider 加 supports_websockets = false
• 模型 ID 不存在 → 见下方「模型不存在」

400 Bad Request

400 的含义高度依赖 error.message，常见几种：

报错文案	原因	解决
Invalid schema for function 'Artifact'	网关严格校验工具 JSON Schema，拒收 Claude Code 的 Artifact 工具（含 \p 类 Unicode 属性转义）	Claude Code 设 CLAUDE_CODE_DISABLE_ARTIFACT=1；或 CC-Switch 勾「禁用 Artifact 工具」
Unexpected value(s) for the anthropic-beta header	网关不接受 beta 头	设 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Extra inputs are not permitted	网关不接受 beta 工具字段（defer_loading、eager_input_streaming）	同上
思考 / reasoning 参数相关报错	第三方部署不接受该档位（如只认 xhigh 及以下，却收到 max）	降低档位；ZCode 改选 high
thinking 参数被拒	网关不支持该参数	设 CLAUDE_CODE_DISABLE_THINKING=1
max_tokens / max_output_tokens 过小	Responses API 拒收小于 16 的值	调大；走 CC-Switch ≥ v3.20.3 会自动夹到最小值
请求体 JSON 解析失败	PowerShell 引号转义问题	见下方命令行注意事项

402 / 额度不足

表现为 insufficient_quota、「额度已用尽」、「余额不足」等文案（具体以 ZiAI 返回为准）：

1. 到控制台确认账户余额与密钥剩余配额
2. 密钥若设了「剩余配额」上限，即使账户有钱也会停
3. 额度耗尽后密钥可能被自动停用 → 充值 / 调整配额后确认密钥状态为启用

429 Too Many Requests

不要立刻重试，那只会让情况更糟。

1. 看响应头有没有 Retry-After，有就按它等
2. 用指数退避：1s → 2s → 4s → 8s
3. 降低并发：不要同时跑多个 Agent 长任务
4. 额度充足却持续 429 → 联系站长确认站点级限速

500 / 502 / 503 / 504

上游或网关侧问题：

• 偶发：ZiAI 会自动重试或切换渠道，一般无需处理
• 持续：某个上游渠道故障。换一个模型试试；若全部模型都失败，联系站长
• 504 / 超时：长思考模型响应慢。调大客户端超时（Claude Code 的 API_TIMEOUT_MS、Codex 的 stream_idle_timeout_ms）

模型不存在 / model not found / model_access_denied

1. 拉取该密钥实际可用的模型列表：

   curl -s https://api.ziai.lol/v1/models \
     -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | jq -r '.data[].id'

2. 逐字复制模型 ID —— 大小写、短横线、点号、日期后缀都必须一致。 gpt-5.2 ≠ GPT-5.2，claude-sonnet-4-5 ≠ claude-sonnet-4.5

3. 若列表里有、调用却报 model_access_denied：

   • 密钥设了模型限制，不含该模型
   • 密钥所属分组无该渠道权限
   • 该模型只有部分协议通道（例如只支持 Chat，不支持 Responses）

4. 若列表里没有：站长未配置该模型的渠道，或已下线。以操练场为准。

模型 ID 可能被重定向

ZiAI 支持模型重定向（把 gpt-4o 映射到实际上游的另一个模型）。 所以以 ZiAI 控制台展示的 ID 为准，不要凭印象填官方名称。

流式输出异常

现象	原因	解决
长时间无输出，最后一次性全部出现	中间层缓冲了 SSE（本地代理、CDN、反代未关闭 buffering）	关掉本地代理直连测试；用 curl -N 确认 ZiAI 侧是否逐段输出
输出到一半断开	触发流空闲超时	Claude Code 设 API_FORCE_IDLE_TIMEOUT=0；Codex 调大 stream_idle_timeout_ms
每个 token 一行 + 大量空 Thought 块	上游在每个 chunk 里回传空 reasoning_content 占位	用 CC-Switch ≥ v3.20.3 走本地转换
工具被重复执行	流式失败后回退到非流式	Claude Code 设 CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1

确认 ZiAI 侧流式是否正常：

curl -N https://api.ziai.lol/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"model":"模型ID","stream":true,"messages":[{"role":"user","content":"数到10"}]}'

这里能逐行输出 data: 事件，说明 ZiAI 侧正常，问题在客户端或本地网络。

连接层错误

现象	原因	解决
Could not resolve host	DNS 问题或域名填错	检查域名拼写；nslookup api.ziai.lol
TLS / 证书错误	系统时间不准、企业中间人证书、证书链不全	校准系统时间；把企业根证书加入信任
连接超时	防火墙、代理、地区网络	换网络测试；确认客户端代理设置（注意 ZCode 默认不读系统代理变量）
网页能打开但 CLI 不通	CLI 走了不同的代理设置	检查 HTTP_PROXY / HTTPS_PROXY / NO_PROXY

配置看起来完全正确却不生效

Codex

• provider 写在了项目级 .codex/config.toml → model_providers、model_provider 等键会被静默忽略，移到 ~/.codex/config.toml
• 改了配置但没重启终端
• 所有命令都报 Error loading config.toml → 配置里残留 wire_api = "chat"，改成 responses

Claude Code

• 环境变量设在当前 shell，但 Claude Code 从别处启动（IDE 内置终端、GUI 启动器）→ 写进 ~/.claude/settings.json 的 env 块最可靠
• 改了 .bashrc 但没 source，或改错了文件（zsh 用户要改 .zshrc）
• 托管设置（组织下发）优先级最高，会覆盖你的用户与项目设置

图形客户端

• CherryStudio：忘开服务商右上角启用开关；或模型没点 + 加入列表
• ChatBox：添加了模型但没保存；或没点「检查」就以为失败
• ZCode：忘开供应商启用开关；或模型 ID 没通过「添加模型」手填
• WorkBuddy：URL 与「自定义协议」开关组合不对
• CC-Switch：卡片没点「启用」；Codex 切换后没重启终端；本地路由映射开了但代理服务没启动

命令行注意事项

bash / zsh / Git Bash

单引号包 JSON，内部用双引号，最省心：

curl https://api.ziai.lol/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KEY" \
  -d '{"model":"模型ID","messages":[{"role":"user","content":"你好"}]}'

PowerShell

curl 是 Invoke-WebRequest 的别名，行为完全不同。请用 curl.exe，或直接用原生 cmdlet：

$body = @{
  model = "模型ID"
  messages = @(@{ role = "user"; content = "你好" })
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri "https://api.ziai.lol/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $env:ZIAI_API_KEY" } `
  -ContentType "application/json" `
  -Body $body

CMD

CMD 对引号处理很别扭，建议把 JSON 写进文件再用 @ 引用：

echo {"model":"模型ID","messages":[{"role":"user","content":"hello"}]} > req.json
curl.exe https://api.ziai.lol/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer sk-xxx" -d @req.json

别把密钥写进命令历史

用环境变量代替明文：

export ZIAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
curl ... -H "Authorization: Bearer $ZIAI_API_KEY"

已经写进历史的话，bash 用 history -d 行号 清理，PowerShell 清 ConsoleHost_history.txt。

还是解决不了

带着这些信息联系站长，排查效率会高很多：

1. 完整报错文案（含 error.message 与 error.type）
2. HTTP 状态码与响应头里的 x-request-id（如果有）
3. 你用的客户端与版本
4. 调用的模型 ID
5. 上面三步定位的结果（哪一步开始不通）
6. 发生时间（便于在日志页定位）

不要在工单里贴完整密钥

提供密钥的前 6 位 + 后 4 位即可定位，例如 sk-abc...wxyz。 完整密钥一旦发出就应视为泄露，请立即在控制台禁用并重建。

相关页面

• 协议不匹配详解 —— 三种协议的完整对照
• 端点与协议 —— 地址该怎么填
• 配置速查表 —— 各客户端字段一览