排查调用错误
打开 1A1API 控制台 小白智库

排查调用错误

先确认调用日志里是否有本次请求，再按错误码或报错原文排查。日志没有请求、请求失败和已成功但未显示，处理方法不同。

返回文档首页 打开 1A1API 控制台 查看调用日志
先分流

第一步：检查调用日志

按报错时间找到对应请求。如果找不到，先检查客户端配置与网络；找到后，再区分请求失败还是客户端未显示结果。

A. 日志里完全没有这次请求先核对时间范围、密钥和状态筛选，刷新后再查。仍没有记录时，检查 Base URL、密钥粘贴位置、客户端代理、网络，以及当前会话是否选中了这套配置。仅凭没有日志，不能唯一确定故障原因。
B. 日志里有请求但失败再按 401 / 403 / 404 / 429 / 522 / 524 排查。此时日志截图比客户端截图更有用。
C. 日志里成功但客户端没显示优先检查客户端超时、流式输出设置、中途断连、代理问题或前端显示问题。
401 Unauthorized

SDK 未读取到 API 密钥、密钥复制不完整，或自定义 HTTP 客户端没有发送 Authorization: Bearer ... 请求头，都可能导致 401。使用官方 SDK 时，请先确认环境变量已经生效；只有自己拼 HTTP 请求时，才需要手动检查 Bearer 请求头。

403 Forbidden

通常不是密钥格式错，而是当前 API 密钥没有权限或额度不可用。请检查：密钥所属分组、模型权限、余额、订阅状态、Responses / Compact / 图片模型能力。

404 Not Found

先读报错原文，区分“接口路径不存在”和“模型不存在”。前者检查最终请求路径是否重复拼接 /v1 或接口名；后者核对模型 ID、分组权限和接口支持。

本帮助站的 OpenAI SDK 示例用 https://1a1api.top/v1，Codex 配置用 https://1a1api.top，Claude Code 用 https://api.1a1api.top。按当前工具的 地址对照填写，不把完整接口路径填进 Base URL。

429 Rate Limited：限流还是额度限制？

先查看返回的 error.code、报错原文和控制台状态，不能只凭 429 判断该重试还是购买额度。

  • 临时限流、并发或服务容量限制：例如明确返回 rate_limit_exceeded 时降低并发；服务返回 Retry-After 时优先按它等待，否则做有总时限的退避重试。
  • 额度不足、周期用量或预算限制：例如明确返回 insufficient_quota 时，先核对 额度、有效期与重置规则，不要自动重试或直接重复充值。
  • 原因不明确：停止连续重试，准备时间、模型、地址、脱敏错误代码和对应日志，再反馈。

官方 API 也区分两类 429，见 错误代码说明；1A1API 的具体原因以本次返回信息和控制台为准。

522 / 524 Cloudflare 超时

522：Cloudflare 与源站连接超时

Cloudflare 未能及时建立源站连接或获得请求确认。先保留报错时间和追踪标识，确认线路是否恢复；降低并发并有限等待。开启流式输出不能直接修复源站连接问题，也不需要因此重复购买额度。

524：已连接源站，等待响应超时

连接已经建立，但源站未能在规定时间内响应。长任务可缩短上下文、拆分工作，并在客户端支持时使用 完整流式调用示例；首次输出前等待过久时，流式仍可能超时。

先查本次请求的日志与扣费状态。已经成功或已收到部分输出时，不要自动重放整次任务。确需切换线路时，请按客户端选择：

  • OpenAI SDK、Cursor、Cherry Studio、OpenCode、WorkBuddy：长任务可尝试 https://api.1a1api.top/v1。
  • 上述 OpenAI 兼容客户端在一般网络不稳定时，也可尝试 https://1a1api.com/v1。
  • Claude Code：保持 https://api.1a1api.top，不要追加 /v1。
  • Codex：不要直接复制带 /v1 的地址，请回到 Base URL 对照确认 Responses root。

两类错误的含义见 Cloudflare 的 522 说明与524 说明。

首 token 很慢

首 Token 耗时是开始收到输出前的等待时间。变慢时，先检查会话是否接近上下文限制；可新开会话、减少历史记录、压缩日志或拆分文件，再用短请求对照。

原文搜索

按英文报错定位原因

客户端可能只显示英文错误信息。以下保留常见报错原文及对应检查项。

Selected model at capacity当前模型或上游账号繁忙。处理：稍后重试、换模型、降低并发；持续出现时联系客服并提供模型 ID 和报错时间。
No available OpenAI accounts support /responses/compact当前分组或上游账号没有 Compact 能力。普通用户请保留日志并联系管理员；管理员再按 Compact 设置路径探测能力或临时切换模式。
API key invalid / UnauthorizedSDK 未读到环境变量、密钥复制不完整或已停用；只有自定义 HTTP 请求才需要手动检查 Bearer 请求头。
model not found / model does not exist可能是模型 ID 写错、分组未开放或所用接口不支持该模型。从控制台或 /v1/models 复制 ID，再确认当前接口与模型权限。
Hostname/IP does not match certificate's altnames证书域名不匹配或代理解析异常。处理：检查 Base URL、代理、DNS、证书缓存，避免填错域名。
timeout / stream interrupted先查日志，区分未开始、已完成和只收到部分输出。未开始时检查网络与超时设置；长任务可拆分或用流式调用。已完成或部分输出时先保存结果，不自动重放整个任务。
高频 FAQ

接入与用量常见问题

我应该填 https://1a1api.top/v1 还是 https://1a1api.top？

OpenAI SDK、Cursor、Cherry Studio 通常填 https://1a1api.top/v1；Codex / Responses 类客户端通常填 root：https://1a1api.top。

为什么我有余额或额度还是 403？

可能是当前 API 密钥所属分组没有该模型权限、额度不足或已到期、订阅额度已用完，或分组没有开启 Responses / Compact / 图片生成能力。

Codex / Claude Code 不能用怎么办？

先确认 Base URL 类型：Codex 通常用 https://1a1api.top，Claude Code 通常用 https://api.1a1api.top。然后用最小请求测试模型 ID 和 API 密钥。

为什么日志里 token 数很大？

大数字可能是缓存读取或上下文缓存相关 token，不一定代表本次新输入。判断扣费先看日志里的“费用”字段。

我应该选高能力模型还是轻量模型？

先从当前 API 密钥可用列表中选择一个通用模型跑通；复杂任务选择当前可用的高能力模型，摘要、分类、批处理等轻量任务再根据质量、速度和费用选择更小模型。

简版：复制就能发 
问题类型：
使用工具：Codex / Claude Code / Cursor / Cherry Studio / OpenCode / WorkBuddy / 其他
模型 ID：
Base URL：
报错时间：
报错截图：
调用日志截图：
API 密钥名称或尾号（不要发送完整密钥）：
高级版：开发者排查 
问题类型：
使用工具和版本：
模型 ID：
Base URL：
请求接口路径：
请求方式：GET / POST
是否开启流式输出（stream）：
HTTP 状态码：
request_id（如果有）：
客户端系统环境：
报错内容：
API 密钥名称或尾号（不要发送完整密钥）：
调用日志截图：
最小复现请求：
你已经尝试过的处理：
安全提醒：不要发送完整 API 密钥，不要把密钥发到群聊、公开截图、公开教程或代码仓库。需要排查时，只提供密钥名称、尾号或控制台截图中的脱敏信息。