跳到主要内容

余额、额度与限流问题

余额不足、API 密钥额度耗尽和请求限流都可能导致调用失败，但处理方法完全不同。排查时不要只看 HTTP 状态码，应结合错误消息、控制台余额、API 密钥设置和使用日志一起判断。

先区分四类限制​

限制含义常见处理方式
账户余额当前账户下所有 API 密钥共同使用的可消费余额增加账户余额或降低消耗
API 密钥额度为某一枚密钥设置的独立消耗上限调整该密钥额度或更换用途正确的密钥
请求频率单位时间内的请求数或 Token 数过高，常用 RPM、TPM 衡量降低发送速度，排队并有限重试
并发数同一时刻仍在处理的请求过多限制并行任务数，等待请求完成后再发送

这几项相互独立。例如，账户余额充足并不代表某枚 API 密钥仍有额度，也不代表当前请求频率没有达到限制。

账户余额和密钥额度有什么区别？​

账户余额属于整个账户，API 密钥额度只限制单枚密钥：

可继续使用的额度 = 账户可用余额与密钥剩余额度中更小的一项

假设账户余额还有 100，某枚密钥的独立额度只剩 5：

  • 这枚密钥最多只能继续消耗自己的剩余额度。
  • 同一账户中的其他密钥不受这枚密钥额度耗尽的直接影响。
  • 如果账户余额耗尽，账户下所有需要付费的密钥都会受到影响。

完整说明参见账户与余额和 API 密钥权限与额度限制。

“无限额度”为什么仍然无法调用？​

API 密钥开启「无限额度」，只表示该密钥没有单独的消耗上限，不表示：

  • 账户余额无限。
  • 请求频率和并发数不受限制。
  • 可以调用所有分组和模型。
  • 密钥永不过期或始终处于启用状态。
  • 上游模型始终有可用容量。

因此，“无限额度”密钥调用失败时，仍需检查账户余额、密钥状态、有效期、分组、模型权限和请求频率。

为什么余额还有数值却提示不足？​

常见原因包括：

  1. 余额小于本次请求需要的预计费用：余额大于零，不代表足以启动任意请求。
  2. API 密钥独立额度已经耗尽：账户余额充足也不能绕过密钥自身的上限。
  3. 请求可能需要预扣：部分模型在开始调用前按预计用量预扣，完成后再按实际用量结算。
  4. 页面数据尚未刷新：应刷新控制台，并以最新余额和调用日志为准。
  5. 客户端实际使用了另一枚密钥：环境变量、SDK 参数或第三方工具可能仍加载旧密钥。
  6. 错误不是余额问题：分组、模型权限或限流错误可能被客户端统一显示为“配额不足”。

可以先减小输入内容和最大输出长度，再发送一次最小请求。如果仍然失败，应查看服务端返回的完整错误消息，而不是只看客户端翻译后的提示。

如何判断 429 是额度不足还是限流？​

429 Too Many Requests 不一定只表示请求过快。不同协议、SDK 和上游服务可能用同一个状态码表示额度或容量问题，应优先读取响应体中的错误消息。

错误消息中的线索更可能的类型应采取的操作
balance、credit、quota、余额、额度不足账户余额或密钥额度检查余额和密钥额度；等待通常无效
rate limit、RPM、requests per minute、请求过于频繁请求频率限制降低请求速度，并使用退避重试
TPM、tokens per minuteToken 速率限制缩短上下文、减少最大输出或降低并发
concurrency、too many concurrent requests并发限制等待在途请求结束，并限制并行任务数
overloaded、capacity、上游繁忙模型或渠道临时繁忙短暂等待后有限重试，必要时更换可用模型

如果错误消息被 SDK 隐藏，可以：

  • 打印异常中的 HTTP 状态码和可读错误消息，但不要输出请求头和完整密钥。
  • 使用最小 cURL 请求复现并查看原始响应。
  • 在控制台的使用日志中按时间和模型定位记录。
不要对所有 429 无限重试

额度型 429 不会因为等待几秒自动恢复。持续重试只会制造更多失败请求和日志噪声。只有频率、并发或临时容量类错误才适合有限重试。

RPM、TPM 和并发分别是什么？​

RPM​

RPM（Requests Per Minute）表示每分钟请求数。大量很短的请求也可能先达到 RPM 限制。

TPM​

TPM（Tokens Per Minute）表示每分钟处理的 Token 数量。一次请求通常会占用输入上下文和预计输出相关的 Token，因此少量长请求也可能达到 TPM 限制。

降低 TPM 压力可以：

  • 删除重复或无关的历史消息。
  • 先总结长文档，再把摘要用于后续请求。
  • 降低 max_tokens、max_output_tokens 或对应协议的最大输出参数。
  • 避免多个任务重复发送同一份大上下文。
  • 把非紧急批量任务分散到更长时间执行。

并发数​

并发数表示同一时刻仍在处理的请求数量。流式请求在输出结束前通常一直占用一个在途请求位置，因此大量长时间流式会话更容易产生并发压力。

可以在应用中使用任务队列或信号量限制并行数。不要通过不断创建新密钥来规避并发限制，因为限制还可能作用于账户、模型、分组或上游渠道。

日志中的 RPM 和 TPM 不一定是限制上限

使用日志页面显示的 RPM、TPM 通常用于观察当前筛选范围或统计窗口内的流量。除非页面明确标注为上限，否则不要把统计值直接当作账户的固定限额。

为什么只有某个模型频繁出现 429？​

只有一个模型失败，而其他模型正常，通常优先检查：

  • 该模型是否使用不同的上游渠道或分组。
  • 该模型是否正处于高负载状态。
  • 该模型单次请求的上下文或输出是否明显更大，更容易达到 TPM 或预扣要求。
  • 密钥所属分组是否仍支持该模型。
  • 客户端是否对这个模型开启了更多并发任务或自动重试。

可以使用同一密钥发送最小请求，再测试同分组内另一个确认可用的模型。如果只有目标模型持续失败，应保存发生时间、模型 ID 和脱敏错误消息后反馈。

为什么充值或调整额度后仍然失败？​

依次检查：

  1. 刷新控制台，确认余额或密钥额度已经显示为最新值。
  2. 确认修改的是客户端实际使用的那枚 API 密钥。
  3. 检查密钥是否仍处于启用状态且没有过期。
  4. 确认密钥分组和模型范围允许当前模型。
  5. 重新发送一次最小请求，避免旧客户端继续执行积压的自动重试。
  6. 查看新请求的错误消息，确认是否已经从额度问题变成限流、模型或参数问题。

增加账户余额不会自动重置 API 密钥的独立额度；提高密钥额度也不会增加账户余额。需要增加账户余额时，参见线下充值。

为什么消耗比预期高？​

实际消耗可能同时包含：

  • 输入 Token 和输出 Token。
  • 多轮对话中重复发送的历史上下文。
  • 缓存读取、缓存写入或模型定义的其他用量。
  • 图片、音频或按次计费项目。
  • API 密钥分组倍率。
  • 超时或失败后由客户端自动发起的重复请求。
  • 后台代理、编程工具子任务或无人值守自动化产生的请求。

排查时在使用日志中按费用排序，并核对模型、API 密钥名称、输入输出 Token、缓存、分组倍率和发生时间。价格计算说明参见模型定价与计费。

如果发现不认识的请求，应立即停用对应密钥、检查使用来源并创建新密钥。不要只提高额度，否则异常调用可能继续消耗余额。

限流时应该怎样重试？​

只对频率、并发或临时容量类错误重试，并设置明确上限：

  1. 如果响应包含 Retry-After，优先等待该响应头指定的时间。
  2. 否则使用带随机抖动的指数退避，例如约 1、2、4、8 秒。
  3. 限制最大重试次数和总等待时间，避免请求无限挂起。
  4. 每次重试前重新判断错误类型；额度、鉴权、权限和参数错误不应原样重试。
  5. 多个工作进程应共享限流状态，避免所有进程同时重试。
错误类型是否等待后重试
账户余额不足否，先增加余额或降低请求成本
API 密钥额度耗尽否，先调整密钥额度
RPM、TPM 或并发限制是，降低流量后有限重试
模型临时繁忙是，有限重试或切换可用模型
密钥无权限或模型不可用否，先修正密钥、分组或模型

流式请求中途失败时，不要把重新请求产生的内容直接拼接到旧输出。涉及写文件、发消息、支付或其他有副作用的工具调用时，还应使用业务 ID 做幂等控制，防止重试重复执行操作。

生产环境怎样减少额度和限流问题？​

  • 为不同应用、环境和成员创建独立密钥，并设置合理额度和有效期。
  • 在客户端统一控制 RPM、TPM 和最大并发，而不是让每个任务自行无限重试。
  • 为批量任务使用队列，并为交互请求保留一定容量。
  • 限制最大输入和输出长度，定期裁剪或总结对话历史。
  • 记录请求时间、模型 ID、状态码、重试次数和脱敏错误消息。
  • 监控余额、单枚密钥用量和高费用调用，设置内部预算告警。
  • 对连续 429 或 5xx 设置熔断，短暂停止向异常模型发送新请求。
  • 为工具调用和其他有副作用的请求设计幂等机制。

快速排查清单​

遇到疑似额度或限流问题时，按顺序检查：

  1. 保存请求时间、模型 ID、HTTP 状态码和完整错误消息。
  2. 查看账户当前余额。
  3. 查看实际使用的 API 密钥是否启用、过期或达到独立额度。
  4. 检查密钥分组、模型范围和目标模型端点类型。
  5. 在使用日志中确认请求使用的密钥、模型、Token 和费用。
  6. 根据错误文字区分余额、额度、RPM、TPM、并发或模型容量问题。
  7. 修正后先发送一条最小请求，再恢复正常流量。

仍无法判断时，可向平台人员提供发生时间和时区、模型 ID、接口路径、状态码、完整错误消息、密钥名称和使用日志中的对应记录。不要提供完整 API 密钥、登录密码或未脱敏的请求头。

需要继续排查连接中断或请求长时间无响应，请阅读网络与超时问题。