错误码与排查

平台错误遵循所接入协议的原生格式：OpenAI 协议返回 { error: { message, type, code } }，Anthropic 协议返回 { type: "error", error: { type, message } }。多数 SDK 会直接抛出包含 status 与 code 的异常，先看 code 再定位。

错误响应格式

OpenAI 协议

{
  "error": {
    "message": "模型 gpt-4-turbo 不存在或未启用",
    "type": "model_not_found",
    "code": "model_not_found",
    "param": null
  }
}

Anthropic 协议

{
  "type": "error",
  "error": {
    "type": "invalid_api_key",
    "message": "API Key 无效"
  },
  "request_id": "req_8f3c1a2b4d5e6f70"
}

错误码对照表

HTTP	code	含义	处理建议
400	invalid_request_error / invalid_json	请求体不是合法 JSON，或缺少必填参数（如 model、messages）	校验 JSON 结构；Anthropic 协议下 max_tokens 必填；确认 Content-Type 为 application/json
401	missing_api_key	请求头没有携带任何 API Key	OpenAI 协议加 Authorization: Bearer sk-zn-xxx；Anthropic 协议加 x-api-key: sk-zn-xxx
401	invalid_api_key	Key 不存在（复制不完整、已被删除、或不是本平台的 Key）	在控制台重新复制完整 Key，注意不要带引号、空格或换行
402	insufficient_quota	可用积分不足，无法覆盖本次请求的预估消耗	充值积分或订阅会员；也可调低 max_tokens 减少预估额度
403	key_disabled / key_expired	该 Key 已被停用或已过期	在控制台启用该 Key，或新建一把 Key 替换
403	account_banned	账号被封禁	联系客服核实账号状态
404	model_not_found	请求的 model 不存在或未启用	使用智脑模型 slug（见模型与价格页），可用 GET /v1/models 拉取清单
429	rate_limit_exceeded	超过每分钟请求上限（未订阅用户默认较低）	降低并发、增加重试退避，或升级套餐提高 RPM
502	upstream_error	上游渠道调用失败（超时、上游报错、上游限流）	稍后重试；持续出现请把请求时间与模型反馈给客服，平台会切换渠道
503	no_available_channel	该模型当前没有可用上游渠道	换用其他在售模型，或等待管理员补充渠道

三步定位问题

先确认 Key 是否可用：用下面的第一条命令请求 /v1/models。返回 401 说明 Key 或请求头有问题，与模型无关。
再确认模型名：返回 404 model_not_found 时，用上一步返回的 id 作为 model 重试。
最后看余额与频率：402 是积分不足，429 是频率超限，两者在控制台都能看到对应记录。

bash

# 1) 验证 Key 与网络是否通
curl https://zhinao.75zs.com/v1/models \
  -H "Authorization: Bearer sk-zn-xxxx"

# 2) 验证指定模型是否可用
curl https://zhinao.75zs.com/v1/chat/completions \
  -H "Authorization: Bearer sk-zn-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"ping"}]}'

常见误区

base_url 层级写错：OpenAI 类客户端应填 https://zhinao.75zs.com/v1； Anthropic 类客户端（含 Claude Code）只填站点根地址。多写或少写 /v1 都会导致 404 或连接错误。
Key 被截断：从网页复制时容易带上换行或省略号，请使用控制台的「复制」按钮。
用错鉴权头：Anthropic 协议用 x-api-key，OpenAI 协议用 Authorization: Bearer；虽然平台两种头都接受，但部分客户端只发送其中一种。
把 402 当成 429：402 需要充值或订阅，重试不会成功；429 只需要退避重试。

仍未解决

请记录 请求时间、模型 slug、HTTP 状态与 code、request_id（Anthropic 协议错误体会带 request_id），通过联系我们页面提供的渠道反馈，我们会在用量日志中定位具体请求。