故障排查
按症状查找的索引——找到您遇到的现象，直接跳转到原因。
重试前检查访问权限
- 检查所需的使用权限是否已生效，并留意其到期时间。
- 确认密钥使用的是所需分组。限时 Claude 套餐使用 Claude Unlimited；Codex 的访问权限是独立的。
- 使用同一个密钥列出模型，选择返回的一个 ID，然后发送一个小型请求。
使用 模型与密钥组 或 智能体设置检查清单 如果你不确定是哪个步骤失败了。
完全无法使用
在排查其他问题之前，先确认基本条件：
curl -s -o /dev/null -w "%{http_code}\n" https://aiprimetech.io/v1/models \
-H "Authorization: Bearer $CLAUDEAPIKEY"成功获取模型列表后，检查所选模型是否在列表中，并发送一个小型生成请求。生成仍可能因模型可用性、使用权限、限制或客户端配置而失败。
按症状分类
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
404 每次调用都出现 | 基础 URL 的以下部分不正确： /v1 处理方式 | 基础 URL |
401 使用刚创建的密钥时 | 请求头不符合所用格式，或末尾有多余空格 | 身份验证 |
402 | 没有可用额度，或套餐已到期 | 充值 · 套餐 |
400 max_tokens | Messages 要求提供 max_tokens；Chat Completions 则不要求 | Messages |
model_not_found | ID 不正确、密钥分组不正确，或该密钥无法使用此模型 | 模型与密钥组 |
| 流式连接已建立，但没有输出 | 按另一种格式的事件结构进行了解析 | 流式传输 |
| 回复在句子中途被截断 | stop_reason: max_tokens | 增大 max_tokens |
| 在 curl 中可用，在 SDK 中失败 | SDK 会在你的基础 URL 后追加自己的路径 | 基础 URL |
| 控制台中未显示用量 | 请求发往了其他密钥或端点 | 检查 ANTHROPIC_API_KEY 未设置 — Claude Code |
频繁出现 429 | 智能体并行度过高 | 速率限制 |
| 账单高于预期 | 上下文随对话轮次增长 | 上下文管理 |
解读错误响应体
状态码说明问题的类别； error.type 和 error.message 字段则说明具体是哪一种问题。记录完整的响应体 — 一个 400 替换为 "missing max_tokens" 以及一个 400 替换为 "invalid role" 需要完全不同的解决方法。
仍未解决
联系 support@aiprimetech.io 并附上端点、模型 ID、状态码和错误响应体。切勿包含你的 API 密钥 — 如果你已经将其粘贴到某处，请先撤销该密钥。