TL;DR
insufficient_quota是计费层错误：请求格式没问题，是「这个 Key 背后的钱」出了状况。- 第一刀切开：你用的是官方订阅登录还是中转/API Key？两者病因完全不同。
- 中转 Key 场景按四条叶子查：余额耗尽 → 额度池/分组限制 → Base URL 指错 → 高倍率模型烧穿余额。
- 官方订阅报 quota 类错误基本等于「配置混了」，先查是不是登录态和 API Key 两套凭据在打架。
图 1：insufficient_quota 决策树——先分分支，再按命中率走叶子（示意图）
第一步：先确认你站在哪条分支上
同一个 insufficient_quota 报错，官方订阅和 API Key 计费的病因毫无交集，所以动手前先回答一个问题——你的 Codex 是怎么登录的？
官方订阅分支：用 ChatGPT 账号 /login 登录，不填 API Key
API 计费分支：配置了 API Key（官方 sk- 开头，或中转平台发的 Key）不确定就看两处：~/.codex/ 下是否存在 auth.json（登录态凭据），以及配置里是否设置了 API Key / 自定义 Provider。两套同时存在时，实际生效的那套以 Codex 启动时的鉴权模式为准（以官方文档为准），这也是分支 A 里「配置混了」的来源。
分支 A：官方订阅登录，却报 quota 错误
订阅制（Plus/Pro）的限制表现为 usage limit（「达到用量上限，X 小时后重置」这类提示），不是 insufficient_quota——后者是 API 按量计费的错误类型。所以订阅账号报这个错，几乎只有一种解释：请求没有走订阅鉴权，而是落到了某把 API Key 上。
自查顺序：
- 回想是否在环境变量里残留过
OPENAI_API_KEY（shell 配置文件里的旧 export 是常客），有就清掉并重开终端。 - 检查 Codex 配置里是否配置过自定义 Provider 或 API Key，与登录态混用。
- 重新
/login刷新登录态，再试。
按这三步清完仍报 quota 错，带着「登录方式 + 报错原文」去官方社区核实，不要反复重登碰运气。
分支 B：中转 / API Key 计费，按四条叶子往下走
API 计费场景下，这个错误就是「这把 Key 现在付不起这笔账」。按命中率排序：
叶子 1：余额真的用完了（命中率最高）
到服务方控制台看两处：账户余额，以及这把 Key 的额度/分组状态。余额为零或低于最低扣费阈值，充值即解。顺手看一眼消费明细——如果消耗速度远超你的预期，直接跳到叶子 4。
叶子 2：额度池 / 分组限制，不是账户没钱
不少中转平台是「账户余额 + Key 级额度池」双层结构：账户有钱，但这把 Key 所属分组/额度池的配额用满，同样报 quota 类错误。核对控制台里 Key 的分组与限额设置；换一把池子没满的 Key 测试可以快速验证是不是这一层。
叶子 3：Base URL 指错了地方
你以为在用中转，实际请求打到了官方——而官方那把 Key 没有余额；或者反过来，把官方 Key 配到了中转地址上。核对方法：
echo "$OPENAI_BASE_URL" # Codex/OpenAI 兼容场景的实际地址
echo "${OPENAI_API_KEY:0:8}" # 只看 Key 前缀，确认是哪家的 Key前缀形态与地址是否同一家，一眼就能对出来。Base URL 的完整配置自检方法见主站Codex API 配置自检。
叶子 4：高倍率模型把余额烧穿了
换用了更强的模型（或服务方把它映射到了高倍率上游）后，同样的对话量消耗翻几倍，余额从「还够用」瞬间见底。核对控制台的模型价目/倍率说明，把模型换回常规档验证——如果换回后恢复正常，就是倍率问题，不是故障。
两分支通用的两条纪律
- 改完任何配置，重开终端再测——环境变量只对新会话生效，「改了没反应」多半是旧会话还在用快照。
- 报错原文要留证：
insufficient_quota常与 429 状态码一同出现，但语义不同（429 是「太快」，quota 是「没钱」）。向服务方反馈时带上完整 JSON 错误体，定位速度完全不同。状态码层面的判断见429/502/530 状态码速查表。
维护说明
本文按 2026-09 的 Codex 常见报错形态与中转平台的通用计费结构整理；订阅限额规则、错误类型命名与平台双层额度结构以官方文档和各服务方说明为准，大版本更新后会复测并更新日期。