2026 年 10 月对照 TokLens 网关代码核对。报错原文以你实际看到的为准。
Codex 请求失败时，会显示状态码和返回的内容。先看状态码，大致就能知道问题出在哪一步：
| 状态码 | 说明 |
|---|---|
| 401 | Key 本身有问题：没带、不存在或已停用 |
| 403 | Key 有效，但这次请求不被允许：过期、余额不足、模型不可用 |
| 429 | 超出了额度或频率限制 |
| 5xx | 服务端或上游暂时出错，一般重试就行 |
TokLens 不会把上游的 401 和 403 原样转给你。普通请求里，上游认证出错显示为 502；WebSocket 连接会显示 upstream websocket authentication failed。所以看到 401 或 403，一般是 TokLens 自己的检查没通过。
先确认是不是 TokLens 返回的
如果看到 usage_limit_reached 或者「You've hit your usage limit」，这是 ChatGPT 套餐的用量上限，不是 TokLens 的报错。说明 Codex 读的还是 ~/.codex 里的 ChatGPT 登录，没有用 TokLens 的配置。改用 toklens-agentic run 启动：
toklens-agentic run --client codex --profile <profile> -- codexTokLens 返回的内容是 JSON，错误码在 code、error.code 或 error.type 里，下面按这些值查。
401：Key 有问题
| 错误码 | 原因 | 处理 |
|---|---|---|
API_KEY_REQUIRED | 请求里没有 Key | 运行 toklens-agentic doctor --client codex --skip-client，它会把 auth.json 和 requires_openai_auth 改回正确的值；自己写配置的话，检查 Key 是否在请求头里 |
INVALID_API_KEY | Key 不存在，常见是复制时少了字符或多了空格 | 重新复制，或在「接入工具」重新生成安装命令 |
API_KEY_DISABLED | Key 已停用或已移除 | 换一个可用的 Key |
USER_INACTIVE、USER_NOT_FOUND | Key 所属的账户不可用 | 发邮件到 [email protected] |
403：Key 有效，但请求被拒绝
| 错误码 | 原因 | 处理 |
|---|---|---|
API_KEY_EXPIRED | Key 过了有效期，「API Key」页的「状态」一栏有到期日期 | 管理员发的 Key 联系管理员延期，或换一个没过期的 Key |
INSUFFICIENT_BALANCE | 余额不足，这个 Key 上也没有可用的余额 | 先充值，再到「钱包」的「为 Key 分配余额」分给这个 Key |
billing_error（error.type） | 余额不足、Key 上的余额用完，或订阅过期、到了用量上限 | 按提示充值、分配余额，或查看「订阅」页 |
MODEL_ACCESS_DENIED | 这个 Key 不能使用当前模型 | 在 Codex 里用 /model 换一个，可用模型见 Key 所属服务的价格表 |
REASONING_EFFORT_DENIED | 这个推理强度不可用 | 调低推理强度，或改 model_reasoning_effort |
ACCESS_DENIED | Key 限制了可访问的 IP，当前网络不在范围内 | 联系发 Key 的管理员 |
SUBSCRIPTION_NOT_FOUND、SUBSCRIPTION_INVALID | Key 属于订阅服务，但订阅不存在、已过期或已暂停 | 到「订阅」页查看 |
GROUP_DISABLED、GROUP_DELETED | Key 所属的服务不可用 | 管理员发的 Key 联系管理员，其他情况发邮件到 [email protected] |
429：超出额度或频率限制
| 返回内容 | 原因 | 处理 |
|---|---|---|
insufficient_quota（API key 额度已用完） | 这个 Key 上的余额用完。Key 上的余额用完就会拦截，不会自动改用钱包余额，所以钱包里有钱也会出现 | 到「钱包」的「为 Key 分配余额」补上，或打开「余额不足时自动补充」；管理员发的 Key 联系管理员 |
rate_limit_exceeded：5 小时、日或 7 天限额已用完 | Key 设了按时间段的消费上限 | 等时间段重置，响应头 Retry-After 是还要等的秒数；「用量明细」里选中这个 Key 可以看到限额和已用金额 |
rate_limit_exceeded：requests-per-minute | 每分钟请求数超过限制 | 放慢一点，或减少同时运行的 Codex |
rate_limit_exceeded：usage quota exhausted for this platform | 账户在这个平台的每日、每周或每月用量到了上限 | 等到下个周期再用 |
rate_limit_error：Concurrency limit exceeded | 同时进行的请求太多 | 减少同时运行的 Codex 会话 |
rate_limit_error：Too many pending requests | 排队的请求已满 | 稍后重试 |
rate_limit_error：Upstream rate limit exceeded | 上游暂时限流，和你的 Key 无关 | 稍后重试 |
USAGE_LIMIT_EXCEEDED | 订阅的每日、每周或每月用量到了上限，有时会显示为 403 billing_error | 等到下个周期，或到「订阅」页查看 |
其他常见报错
| 报错 | 原因 | 处理 |
|---|---|---|
404 model_not_found | 模型名写错，或当前服务没有这个模型 | 用 /model 换一个 |
400，内容含 input_tokens exceeds | 这次请求的上下文太长 | 用 /compact 压缩对话，或开一个新会话 |
502 upstream_error、503、504 | 服务端或上游暂时出错 | 稍后重试；持续出现就发邮件到 [email protected]，附上时间和模型 |
查到原因之后
改完配置或者补完额度，发一条新请求试试：
toklens-agentic run --client codex --profile <profile> -- \
codex exec --skip-git-repo-check "Reply with exactly TOKLENS_OK."成功后可以在「用量明细」里看到这条请求。配置文件每一行的含义见 Codex 接入 TokLens：config.toml 每一行是什么意思。