额度不足Billing / Quota / Budget
insufficient quota：余额不足、额度用完怎么解决
insufficient quota 不是代码格式问题，而是账号可用额度、预算上限、账单状态或免费层限制不足。
排查结论
先用最小请求隔离问题：只保留 API Key、Base URL、模型名和一条 ping 消息。最小请求失败，先修配置；最小请求成功，再回到业务代码排查并发、上下文和部署环境。
1. 问题现象
- 错误信息包含 insufficient_quota、quota exceeded、balance not enough、credit exhausted 或 payment required。
- 小号、新项目或刚创建的 Key 立刻失败，但老项目还能调用。
- 充值后仍失败，可能是充错账号、充错项目、账单未刷新或预算上限未解除。
- ChatGPT、Claude Pro、Gemini Advanced 能聊天，但 API 调用仍提示没额度。
2. 最可能原因
API 账户没有余额，或免费额度已经过期/用完。
平台把 Chat 订阅和 API 计费分开，订阅不提供 API 额度。
项目设置了预算上限、欠费停机或账单验证未完成。
使用了价格更高的模型，单次请求消耗超过预期。
团队/组织下有多个项目，Key 属于没有余额的项目。
3. 快速排查清单
1
登录控制台看 Billing 和 Usage
不要只看聊天产品订阅页；API 控制台的余额、用量和账单状态才是依据。
2
确认 Key 所属项目
多项目、多组织时，充值和 Key 必须在同一个项目或账号下。
3
确认免费额度是否过期
很多平台的新用户额度有有效期，不是永久余额。
4
降低模型和 max_tokens
先用便宜模型、短输出跑通，再切回高阶模型。
5
充值后等待刷新
国内支付通常很快，但仍可能需要几分钟；失败时查看支付订单和账号是否一致。
4. 对应 API 的特殊情况
OpenAI
ChatGPT Plus/Pro 与 API Billing 分开计费。开了 ChatGPT 订阅，API 仍需要单独充值或绑定账单。
Claude
Claude Pro/Max 订阅和 Anthropic Console API 也是两套计费。API 需要在 console.anthropic.com 单独开通。
Gemini
Google AI Studio 免费层、Google Cloud Billing、Vertex AI 项目额度要分开检查。
DeepSeek / 通义千问 / Kimi / 智谱
国内平台通常在控制台有余额、资源包或 Tokens 页面；充值和实名认证状态会影响可调用额度。
5. 可复制的修复示例
捕获额度不足并切到便宜模型
typescript
async function ask(client: any, messages: any[]) {
try {
return await client.chat.completions.create({
model: process.env.PRIMARY_MODEL,
messages,
max_tokens: 800,
});
} catch (error: any) {
const code = error?.code ?? error?.error?.code;
if (code !== "insufficient_quota") throw error;
return client.chat.completions.create({
model: process.env.FALLBACK_MODEL,
messages,
max_tokens: 300,
});
}
}降级只能作为临时兜底，根因仍要回控制台处理余额或账单。
给批量任务加预算保护
typescript
const DAILY_TOKEN_BUDGET = 200000;
let usedTokensToday = 0;
function assertBudget(estimatedTokens: number) {
if (usedTokensToday + estimatedTokens > DAILY_TOKEN_BUDGET) {
throw new Error("已达到今日 Token 预算，停止继续调用 API");
}
usedTokensToday += estimatedTokens;
}先在业务侧阻止失控循环，避免额度被异常任务一次性耗尽。