请求失败时，不要同时修改 Key、模型、地址和客户端设置。最有效的方法是先把问题缩小到最小 curl，再按“网络 -> 地址 -> Key -> 模型 -> 余额 -> 上游 -> 客户端”的顺序逐项检查。

文档复核：2026-10-18。2026-10-16 已验证 Codex CLI 0.154.0、Claude Code 2.1.220 和四项 Python / Node SDK 的成功调用及对应日志，版本详见接入地址选择；这不是对本页每种错误、网络环境或恢复措施都进行故障注入的证明。出现新错误时，保留实际版本、时间、完整结束状态及脱敏日志。

本页按现象定位；错误码与重试负责状态码参考。地址规则看接入地址选择，Key 生命周期看获取 API Key，不要反复新建相同问题的配置。

先按现象选路径

当前现象	从哪里开始	怎样确认恢复
DNS、证书错误或连接超时	下方第一步；同时参考 状态页	在本人网络建立 HTTPS 连接，再继续 API 验证
401、403 或模型列表为空	第二、三步及 Key 设置	同一 Key 能看到目标模型，目标协议真实请求完成
404、HTML 登录页或重复 /v1	地址对照	实际 URL 与协议一致，返回对应 API 结果
模型不存在、余额或 Key 额度不足	本页模型/余额章节与计费说明	本人权限和额度有效，最小调用完成
200 但没有正文、流式中断或客户端一直等待	第四、五步及下方“200 仍失败”	返回可用结果，协议正常结束且站内日志可关联
curl 成功但工具失败	本页 Codex / Claude 章节或 SDK 教程	同一地址、Key、模型在目标客户端完成调用

排查前先记录这些信息

请先记录，但不要记录完整 Key：

• 请求发生的时间和时区。
• 使用的客户端及版本。
• Base URL 和接口路径。
• 模型名。
• HTTP 状态码和完整错误文字。
• 控制台「使用日志」中是否出现记录。

可以把 Key 脱敏成 sk-abcd...wxyz，不要把完整值放进截图、群聊或工单。

第一步：确认官网和 API 都能访问

打开浏览器分别访问：

https://console.zcloudapi.com
https://api.zcloudapi.com

模型 API 根地址不一定显示网页，但不应出现 DNS 或 TLS 证书错误。

macOS / Linux 检查：

curl -I --connect-timeout 10 "https://api.zcloudapi.com"

Windows PowerShell 检查 443 端口：

Test-NetConnection api.zcloudapi.com -Port 443

如果这里超时：

1. 在当前单条测试命令中比较直连与代理，方法见下方“代理问题”；不要为排障关闭系统 VPN、TUN 或修改全局 DNS。
2. 换一个网络，例如手机热点。
3. 检查企业防火墙是否允许 api.zcloudapi.com:443。
4. 不要改用服务器 IP，API 应始终通过 HTTPS 域名访问。

第二步：确认 Key 已正确传入

macOS / Linux：

export ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"
test -n "$ZHICLOUD_API_KEY" && echo "Key 已设置"

Windows PowerShell：

$env:ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"
if ($env:ZHICLOUD_API_KEY) { "Key 已设置" } else { "Key 未设置" }

注意检查：

• 是否误粘贴了整段连接 JSON，而不是 api_key 值。
• Key 前后是否有空格或换行。
• Key 是否已经停用、删除、过期或达到自身额度上限。
• 当前终端是不是设置变量之后的同一个窗口。

第三步：只测试模型列表

macOS / Linux：

curl -i "https://api.zcloudapi.com/v1/models" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY"

Windows PowerShell：

curl.exe -i "https://api.zcloudapi.com/v1/models" `
  -H "Authorization: Bearer $env:ZHICLOUD_API_KEY"

结果判断：

结果	说明	下一步
200 且模型不为空	网络、地址和 Key 基本正常	复制一个模型继续最小请求
200 但列表为空	Key 或用户分组没有可见模型	检查分组和模型限制
401	Key 无效或认证 Header 不正确	重新创建测试 Key 并再次复制
403	用户、分组或 Key 权限不足	检查账号权限和 Key 设置
超时 / TLS 错误	网络、代理、DNS 或证书链问题	回到第一步

第四步：发送最小非流式请求

从本人 Key 的 /v1/models 返回结果复制一个支持 Chat Completions 的完整文本模型 ID，替换下面的 YOUR_TEXT_MODEL_ID 占位符，不要手工猜名称。

curl -i "https://api.zcloudapi.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_TEXT_MODEL_ID",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "max_tokens": 16,
    "stream": false
  }'

第一次排障不要使用流式输出、工具调用、图片输入或复杂参数。如果最小请求成功，再逐项加回原请求字段，找到具体是哪一个字段触发问题。

第五步：在使用日志中定位

1. 登录 https://console.zcloudapi.com。
2. 打开「控制台 -> 使用日志」。
3. 按模型和大概时间查找刚才请求。
4. 打开记录，查看状态、Token、渠道错误和扣费。

判断方式：

• 没有消费记录不等于请求一定没到平台：鉴权、限流等错误可能发生在消费日志写入之前。先看实际响应、地址和脱敏请求标识，再检查客户端是否用了其他 Provider。
• 响应为 401 / 403：检查 Key 和分组权限，不要求先找到一条消费日志。
• 有请求且上游错误：记录模型和时间，有限重试后联系支持。
• 有成功请求但客户端报错：客户端可能无法解析返回格式或流式事件。

HTTP 200 仍失败时怎么查

1. 非流式检查协议的成功状态、结束原因和可用结果；响应中有错误对象、只有推理内容、空输出或被输出上限截断时，不算本页最小测试通过。
2. 流式请求必须等到相应协议完整结束，不能把收到首个 SSE 数据块当作调用完成；记录中断发生的时间。
3. 在控制台按同一时间、模型和用量核对。若响应含 X-Oneapi-Request-Id，使用它辅助关联；上游的 request ID 和列表展示序号可能不同。
4. 输出上限不足时，适当提高上限后做一次小请求；只有客户端失败时，再查看代理缓冲、超时与客户端版本，不要无限重试。

按状态码处理

状态码	常见原因	处理步骤
400	参数、协议或模型能力不匹配	退回最小请求，删除可选参数，再按对应协议逐项加回
401	Key 错误、停用或未正确传入	重新复制 Key，检查 Header 和当前终端环境变量
403	分组或模型权限不足	查看 /v1/models，检查 Key 的模型限制和用户分组
404	URL 拼错或接口不存在	检查 /v1 是否缺少或重复，确认接口类型
408	请求或上游超时	缩短输入、降低输出上限、增加客户端超时后重试
429	频率、并发或上游限流	降低并发，使用指数退避，不要立即无限重试
5xx	网关或上游临时异常	记录时间和模型，有限重试；持续失败时联系支持

model not found 的完整排查

1. 重新调用 /v1/models。
2. 在返回 JSON 中查找目标模型。
3. 如果不存在，检查 Key 的模型限制和用户分组。
4. 如果存在，直接复制 data[].id，不要手工输入。
5. 检查大小写、短横线、版本号和前后空格。
6. 确认请求发往正确协议，例如 Claude Messages、Responses 或 Chat Completions。
7. 用最小非流式请求重新测试。

模型广场有该模型，不等于当前 Key 一定有权限。最终以当前 Key 的 /v1/models 为准。

余额或额度不足

按顺序检查：

1. 打开「钱包」，确认账号总余额。
2. 查看兑换码是否已经成功到账。
3. 打开 API 密钥详情，检查这条 Key 是否有单独额度上限。
4. 打开 模型定价页面，确认模型是按 Token 还是按次计费。
5. 在「使用日志」核对最近请求的输入、输出和扣费。
6. 如果余额刚刚充值，刷新页面并重新发起一次小请求。

Codex 排查顺序

1. 用 curl 测试 /v1/models。
2. 用 curl 测试 /v1/responses。
3. 打开 ~/.codex/config.toml，检查 base_url = "https://api.zcloudapi.com/v1"。
4. 检查 wire_api = "responses"。
5. 检查 env_key 和当前终端变量名一致。
6. 删除 requires_openai_auth = true。
7. 完全退出 Codex，再运行 codex exec --skip-git-repo-check "只回复 OK"。

如果 curl 成功但 Codex 失败，问题才属于 Codex 配置。完整步骤见「配置 Codex」。

Claude Code 排查顺序

1. 用 curl 测试 /v1/models。
2. 用 curl 测试 /v1/messages。
3. 检查 ANTHROPIC_BASE_URL=https://api.zcloudapi.com，不能附加 /v1。
4. 检查 Key 是否放在 ANTHROPIC_AUTH_TOKEN。
5. 检查目标 Claude 模型存在于 /v1/models。
6. 清除 Bedrock、Vertex 或其他冲突 Provider 环境变量。
7. 关闭所有终端，重新打开后运行 claude -p "只回复 OK"。

图片生成排查顺序

1. 确认图片模型出现在 /v1/models。
2. GPT、Gemini 和 Grok 生图统一使用 /v1/images/generations。
3. 图片编辑统一使用 /v1/images/edits，并通过 multipart 的 image 字段上传原图。
4. 检查钱包是否足够支付单次图片费用。
5. 把尺寸降到 1K，数量设为 1，增加客户端超时。
6. URL 返回后立即下载；Base64 Data URL 很长属于正常现象。

代理问题

macOS / Linux 查看代理变量：

env | cut -d= -f1 | grep -i proxy

临时关闭当前终端代理后测试：

env -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY \
  -u http_proxy -u https_proxy -u all_proxy \
  curl -I "https://api.zcloudapi.com"

Windows PowerShell 查看代理：

Get-ChildItem Env: | Where-Object { $_.Name -match 'PROXY' } | Select-Object -ExpandProperty Name
netsh winhttp show proxy

只清除测试子进程的环境变量，不会停止系统代理；如果正在使用 TUN，测试仍可能经过它，不能把结果当作已证明完全直连。上面的 Unix 命令只显示变量名，避免代理 URL 中的认证信息进入排障输出。Windows 查看环境变量时也只需记录变量名，分享 netsh 输出前先脱敏。

如果子进程测试恢复，检查代理规则是否错误拦截 api.zcloudapi.com，不要在生产代码里永久禁用所有代理。

联系支持模板

仍然无法解决时，发送邮件到 support@zcloudapi.com，可以使用下面模板：

客户端及版本：
操作系统：
请求时间和时区：
Base URL：
接口路径：
模型名：
HTTP 状态码：
完整错误文字：
使用日志是否有记录：
已经完成的排查步骤：
网关 X-Oneapi-Request-Id（如有）：

不要发送完整 API Key、密码、私钥、Authorization Header 或包含敏感数据的完整请求正文。

返回文档中心，按使用目标选择其他接入路径。

需要判断状态页与个人请求结果的关系时，阅读状态页与请求成功验证，分开核对探测、日志、客户端结束和任务产物。