Codex 已登录却提示 API 额度不足？登录方式、401 与 429 排查

适用范围与核对日期

本文由 AIXiamo（AI夏末）整理，按 2026 年 9 月 8 日的 OpenAI 官方文档核对，命令名称与本地 Codex CLI 0.153.4 的帮助信息交叉检查。面向普通本地 CLI 使用；企业工作负载身份、第三方代理的认证与账单需结合各自配置。

本文没有使用读者的真实凭据发起测试。下方错误样例是人工构造的教学数据，离线运行只能验证分类逻辑，不能证明某个账号的实际权限、余额或服务状态。

一、先确认：到底是哪一次请求失败？

例如，Codex 可以分析项目，但运行项目中的 Python 脚本时出现 API 额度错误。此时应先检查该脚本的请求目标和凭据来源；仅退出 Codex 重新登录，可能完全没有改变脚本的配置。MCP 服务返回的错误也按同样方法定位。

保留报错前后的必要上下文：执行了什么操作、错误出现在哪个工具结果、目标服务是谁。不要只截取“429”三个字符，也不要将一次工具错误扩展成“整个 Codex 不能用”。下面是一个可自行填写的记录模板，未知项直接填未知。

发生时间：YYYY-MM-DD HH:mm（北京时间）
运行位置：本机 / WSL / SSH 远程
失败操作：Codex 对话 / 项目脚本 / MCP 工具
请求目标：只记录主机名，去掉查询参数与凭据
HTTP 状态：
error.type：
error.code：
错误摘要：仅保留已脱敏的必要文字
最近单项变化：

二、检查 CLI 登录方式，不读取凭证文件

在实际发生问题的终端运行下面两条命令。codex login status 显示当前认证方式；官方 CLI 文档说明，退出码为 0 表示存在登录凭据。它不是 API 余额查询，也不能替代一次目标请求的权限验证。分享输出前遮盖其中的账号信息或密钥片段。

普通 Codex 本地使用支持 ChatGPT 登录与 API Key 登录。API Key 使用 OpenAI Platform 计费；ChatGPT 订阅与 API 账单分开。因此浏览器里已经开通 Plus / Pro，并不能说明当前 API 请求获得了可用额度。

如果同一台机器装过多个版本，可在 macOS / Linux / WSL 使用 command -v codex，或在 PowerShell 使用 Get-Command codex，核对实际执行路径。不要拿本机的状态去解释远程终端的报错。

codex --version
codex login status

三、配置看什么：provider、目标主机与生效范围

若使用自定义 provider，重点核对选中的 model_provider、对应 provider 的 base_url 和认证配置。只查看必要字段，不公开整份配置、环境变量或 auth.json。不能因为设置过 OPENAI_API_KEY，就直接认定所有 Codex 请求都在使用它。

官方认证文档明确：自定义 provider 可以用 env_key 指向环境中的密钥；requires_openai_auth 为 true 时，则采用 OpenAI 认证并忽略 env_key。实际判断要结合当前选中的 provider。

配置还可能受到 CLI 参数、profile、受信任项目内 .codex/config.toml 和用户级配置的覆盖。遇到“改了没有用”，先查当前运行采用哪一层，再修改；不要同时清空多份配置。配置优先级的完整规则见文末官方来源。

四、401 与 429：依据细分原因处理

对于 OpenAI API 的 401，核对实际使用的凭据、组织／项目归属、权限以及允许的请求来源。它不能用来判断余额。对于 429，继续读取 error.code；error.type 为 insufficient_quota 时，仍需区分下列具体限制。

• 限流或 slow_down：降低并发和请求速率；有 Retry-After 时遵循其等待要求。
• credit_balance_exhausted：核对 API 组织的预付余额。
• organization_spend_limit_exceeded：核对组织消费上限。
• project_spend_limit_exceeded：核对当前项目消费上限。
• organization_usage_limit_exceeded：核对平台分配给组织的用量上限，必要时申请调整。
• 缺少细分代码：结合错误说明与对应服务后台继续判断，不自动归类为“没钱”。

五、离线示例：不要把所有 429 都交给重试循环

下面是本文编写的最小分类函数。保存为 classify_api_error.py 后，用 python3 classify_api_error.py 运行；Windows 可使用已安装的 Python 3 启动命令。示例不读环境变量、不读取凭据，也不调用网络。

函数只返回排查方向。未知代码保留为 unknown_429，余额与限制问题分开，且不会自动购买额度或修改上限。第三方网关、自定义错误结构以及非整数状态码不属于这个示例的已验证输入约定。

# 人工构造的教学样例，仅用于离线分类。
def classify(status, body):
    error = body.get("error") if isinstance(body, dict) else None
    error = error if isinstance(error, dict) else {}
    code = error.get("code")
    kind = error.get("type")

    if status == 401:
        return "check_auth"
    if status != 429:
        return "inspect_other_error"
    if code == "credit_balance_exhausted":
        return "check_api_balance"
    if code in (
        "organization_spend_limit_exceeded",
        "project_spend_limit_exceeded",
        "organization_usage_limit_exceeded",
    ):
        return "check_api_limit"
    if kind == "insufficient_quota" or code == "insufficient_quota":
        return "inspect_quota_detail"
    if code == "slow_down" or kind == "rate_limit_error":
        return "reduce_rate"
    return "unknown_429"


samples = [
    (401, {"error": {"message": "demo only"}}),
    (429, {"error": {"code": "credit_balance_exhausted"}}),
    (429, {"error": {"code": "project_spend_limit_exceeded"}}),
    (429, {"error": {"type": "insufficient_quota"}}),
    (429, {"error": {"code": "slow_down"}}),
    (429, {}),
]

for status, body in samples:
    print(classify(status, body))

六、怎样核对输出，再选择下一步？

上面的六组教学输入应依次输出下列结果。前三项分别转向认证、API 余额和 API 限制；第四项表示还缺少具体额度原因；第五项才转向速率调整；最后一项需要继续取证。即使 HTTP 状态相同，处理路径也不相同。

真正编写重试逻辑时，只对已经识别的适合重试情况启用退避。缺少等待提示的限流可使用指数退避加随机延迟，并设置次数或总时长上限；不要同时叠加 SDK 重试和无上限的外层循环。失败请求也可能计入速率限制，快速重复发送会使情况更差。

核对结果后，每次只修正一个条件并记录变化。消费上限由有权限的人按预算决定，不能为了消除提示就自动取消限制。若准备切换 Codex 认证，先确认可以重新登录：codex logout 会清除保存的登录，CLI 与 IDE 扩展共享登录缓存，可能需要一起重新认证。

check_auth
check_api_balance
check_api_limit
inspect_quota_detail
reduce_rate
unknown_429