返回博客

故障排查指南

常见连接错误及其修复方法

连接 CheapTokens API 时 401、402、400、404、413、429 和 503 分别代表什么，响应长什么样，以及如何逐一修复。

作者：CheapTokens Team发布于 3 分钟阅读

终端中列出的 HTTP 状态码 401、402、400、404 和 429 及简短说明
本页内容
  1. 快速检查
  2. 401 — API 密钥无效
  3. 402 — 余额为空或请求中没有密钥
  4. 404 — 地址错误
  5. 400 — 找不到模型
  6. 413 — 请求过大
  7. 429 — 请求过多
  8. 503 — 模型暂时不可用
  9. 长时间等待和超时

几乎所有的连接问题都归结为四件事：地址、密钥、模型 ID 和余额。先做下面的快速检查，然后找到你的状态码。这里引用的响应体是 API 的实际响应（2026 年 10 月）。

快速检查#

bash
# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

如果第一条命令失败，原因可能是你这边的网络问题、地址拼写错误——或者服务本身暂时不可用。如果只有第二条失败，请在下面查找它的状态码。如果两条都正常但你的工具不行，请把工具的设置与这两条命令对比一下。

401 — API 密钥无效#

json
{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Anthropic 风格的客户端会以它们的格式收到同样的错误：

json
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

原因：

  • 密钥复制时漏了字符、多了空格或引号；
  • 密钥在控制台中被轮换过——旧的已不再有效；
  • 设置了其他服务的密钥（例如 OpenAI），而不是 CheapTokens 的密钥；
  • 当前终端中环境变量为空：echo ${#CHEAPTOKENS_API_KEY} 会打印它的长度。

控制台只显示一次密钥。如果丢失了，请按 Rotate 获取新密钥，并在所有使用它的地方更新。

402 — 余额为空或请求中没有密钥#

API 在两种不同情况下返回 402：

  1. 余额已用完。 请求从余额中扣费；余额耗尽后，密钥会被暂停。在控制台充值后请求即可恢复。
  2. 请求中完全没有密钥。 如果缺少 Authorization 请求头（Anthropic 风格客户端则是 x-api-key），API 会返回 402，类型为 insufficient_funds。检查你的工具是否真的发送了密钥：OpenAI 风格是 Authorization: Bearer <key>。

404 — 地址错误#

json
{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

路径中有拼写错误——这里写成了 completion，而不是 completions。其他常见原因：

  • 基础 URL 缺少 /v1。 OpenAI 风格的客户端需要 https://api.cheaptokens.dev/v1。没有 /v1 时请求会错过 API，你会得到普通的 HTML 404 页面而不是 JSON。
  • /v1 出现两次。 有些客户端会自己加上 /v1；那么基础 URL 必须是根地址 https://api.cheaptokens.dev。Anthropic 风格的客户端始终使用根地址。

400 — 找不到模型#

json
{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

模型 ID 必须是完整 ID，包括斜杠前的前缀：deepseek-ai/DeepSeek-V4-Flash-0731，而不是 deepseek-v4-flash。大小写无关紧要。错误消息会列出可用的 ID，完整列表始终在 GET /v1/models。

请求体格式错误时也会返回 400——例如空的 messages 数组（messages field is required and must be a non-empty array）或没有 role 的消息。

413 — 请求过大#

请求体限制为 16 MB。智能体把巨大的文件或日志放进上下文时可能会触发它。只发送模型需要的部分，并裁剪过长的工具输出。

429 — 请求过多#

如果收到 429，请放慢速度。响应中包含 Retry-After 请求头，给出需要等待的秒数。官方 OpenAI SDK 会自动重试（max_retries）；在你自己的代码中，下一次尝试前等待 Retry-After。

503 — 模型暂时不可用#

模型可能暂时不可用；此时 API 会返回 503，类型为 model_unavailable，网站上的模型卡片会显示“暂时不可用”。稍后重试，或把 model 字段切换到另一个模型——密钥和地址保持不变。

长时间等待和超时#

像 zai-org/GLM-5.3-Flash 这样的推理模型在回答前会先思考，因此第一个 token 可能需要一段时间。使用流式传输或提高客户端超时——例如 OpenAI SDK 中的 timeout=120。

标签: