HTTP状态码429表示请求超限，Qoder采用QPS、RPM和并发数三重限流；应对策略包括：一、依Retry-After头动态冷却；二、客户端部署令牌桶限流；三、接入Nginx反向代理；四、多密钥轮询代理。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您调用 Qoder API 时返回 HTTP 状态码 429，并提示“请求次数过多”，说明客户端在单位时间内发起的请求数已超出服务端设定的速率配额。Qoder 当前采用多维限流机制，涵盖每秒请求数（QPS）、每分钟请求数（RPM）及并发连接数三重阈值。以下是应对该错误的具体冷却策略与代理接入方案：
一、基于 Retry-After 响应头的动态冷却策略
Qoder 在返回 429 响应时，强制携带 Retry-After 响应头，其值为整数秒数，表示客户端必须等待的最小冷却时间。该字段优先级高于任何本地退避逻辑，是服务端精确调度的指令信号。
1、捕获响应状态码，确认其值严格等于 429。
2、从响应头中提取 Retry-After 字段值；若字段缺失，则拒绝执行后续冷却逻辑并抛出配置异常。
3、调用系统级休眠函数，等待精确至毫秒级的 Retry-After 所示秒数 + 100ms 抖动偏移，避免集群内请求同步苏醒。
4、休眠结束后立即重发原始请求，不修改请求体、Header 或签名参数。
二、本地令牌桶限流器部署
在客户端进程内嵌入令牌桶算法实例，将 Qoder 的 QPS 阈值作为桶容量与填充速率基准，实现请求流量的主动整形，从源头规避触发限流。该方式不依赖服务端响应，适用于高确定性调用场景。
1、查阅 Qoder 控制台“API 密钥详情页”，确认当前密钥所属套餐的 QPS 上限值（如：免费版为 3，基础版为 15）。
2、初始化令牌桶：设置桶容量 = QPS 上限值，填充速率为 QPS 上限值 / 1 秒，使用滑动窗口式时间戳校准填充时机。
3、每次发起请求前，调用 acquire() 方法阻塞等待可用令牌；若超时未获取，直接丢弃本次请求并记录告警。
4、成功获取令牌后发送请求，无论响应成功或失败，均不退还令牌，确保速率刚性约束。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
三、轻量级反向代理层接入
通过部署独立反向代理节点，将原始客户端请求统一收敛至代理服务，由代理完成请求排队、限流熔断、重试封装与响应缓存，使上游业务代码完全无感限流细节，同时支持跨客户端共享配额上下文。
1、在私有网络中启动 Nginx 实例，启用 ngx_http_limit_req_module 模块，配置 key 为 $binary_remote_addr，zone 名为 qoder_limit:10m。
2、定义限流规则：rate = 对应密钥 QPS 上限值r/s，burst = QPS 上限值 × 2，nodelay 启用突发允许。
3、将 upstream 指向 Qoder 官方 API 域名，并在 proxy_set_header 中透传原始 X-Qoder-API-Key 与 X-Real-IP。
4、客户端 DNS 解析目标切换为该代理地址，所有请求经由代理转发，不再直连 Qoder 后端。
四、多密钥轮询代理策略
当单一密钥配额无法满足业务峰值需求时，可预先申请多个 Qoder API Key 并构建轮询代理层，在请求发出前按哈希或计数器选择密钥，实现配额资源的水平扩展，本质是将单点限流转化为分布式容量池。
1、在控制台申请至少 3 个同等级套餐的 API Key，确保各密钥具备相同 QPS 与并发上限。
2、维护一个内存内密钥列表，采用 一致性哈希算法映射请求 ID 到密钥索引，保障同一会话始终命中同一密钥。
3、为每个密钥独立维护请求计数器与最近一次 429 时间戳，当某密钥连续触发两次 429 且间隔小于 60 秒，自动将其临时剔除出轮询池 5 分钟。
4、代理层在转发前重写 Authorization Header，注入选中的密钥，并附加 X-Qoder-Routed-Key-ID 标识用于审计追踪。
