Composio 平台速率限制与 429 处理：组织级配额、响应头与降级策略完全指南

Composio 对平台 API 实施按组织共享的速率预算，所有需要认证的端点（工具执行、Connected Accounts、Triggers 等）共用同一份配额。本文以 docs/kb/articles/platform-rate-limits.md 为主线，结合官方 Rate Limits 参考文档 与仓库源码中的错误提取实现，系统讲解各套餐的速率上限、限流响应头（X-RateLimit-* 与 Retry-After）、429 的正确处理方式，以及升级组织后仍触达旧上限时的排查路径，帮助你构建稳定、可观测、不被打爆的 Agent 工作负载。

一、限流模型：按组织共享的每分钟预算

Composio 的速率限制按组织（organization）维度施加，而非按单个 API Key、单个项目或单个工具计算。在固定的 1 分钟窗口内，所有经过认证的端点共享同一份预算——工具执行、Connected Accounts、Triggers、Webhook 订阅等全部计入，也就是说下表给出的数值是组织在所有 API 调用上的总量，而不是某一类调用的单独配额。

这一设计意味着：

• 并发执行多个 Toolkit 时，所有请求共同消耗同一预算；
• 高频轮询触发器的应用会与其他业务请求互相挤占配额；
• 扩容时应优先评估组织整体用量，而不是只看单一端点的调用量。

从仓库的 CLI 错误提取实现（ts/packages/cli/test/src/utils/api-error-extraction.test.ts）可以看到，平台将限流错误归类为 rate_limited slug，错误码为 42901，这与 HTTP 语义中的 429 一一对应，说明限流是平台错误体系中的一等公民，应用层应将其作为可预期、可捕获的错误类型处理。

二、各套餐速率上限（按组织）

当前已发布的组织级速率上限如下：

套餐	速率上限	窗口
Starter / Hobby	2,000 请求	1 分钟
Growth / Pro	10,000 请求	1 分钟
Enterprise	自定义（Custom）	-

注意：KB 文章（docs/kb/articles/platform-rate-limits.md）使用 "Starter / Hobby" 与 "Growth" 的命名，而官方 Rate Limits 参考文档 的表格中对应写法为 "Hobby" 与 "Pro"（Enterprise 均为 Custom）。套餐命名在不同时期可能调整，引用某个套餐的具体数值前，务必以当前官方文档为准；同时官方明确：Enterprise 是"自定义（Custom）"配额，不应将其描述为"无限（unlimited）"。

参考文档 docs/content/reference/rate-limits.mdx 中的表格如下：

Plan	Rate limit	Window
Hobby	2,000 requests	1 minute
Pro	10,000 requests	1 minute
Enterprise	Custom	-

三、限流响应头：无需猜测用量

每次 API 响应都会携带限流相关的响应头，客户端可以据此精确跟踪当前窗口内的用量，而无需猜测：

响应头	说明
X-RateLimit	当前窗口允许的请求总数
X-RateLimit-Remaining	当前窗口内剩余可用请求数
X-RateLimit-Window-Size	窗口大小（例如 60s 表示 60 秒）
Retry-After	距窗口重置的秒数（仅在 429 响应中出现）

关键实践：在每次响应中读取 X-RateLimit-Remaining，实时掌握窗口内剩余余量，据此动态调整请求节奏；当收到 429 Too Many Requests 时，响应体与响应头中包含窗口信息，且 429 响应会携带 Retry-After——必须在重试前严格遵守 Retry-After 给出的等待秒数，而不是立即重试或密集轰炸端点。

超限时的响应体示例（来自官方参考文档 docs/content/reference/rate-limits.mdx）：

{
  "message": "Rate limit exceeded. Limit: 10000 requests per 1 minutes"
}

四、429 的标准处理流程

结合 docs/kb/articles/platform-rate-limits.md 与官方参考文档 Rate Limits 中的 Best Practices，推荐的 429 处理流程如下：

1. 读取 X-RateLimit-Remaining：每次响应都检查剩余额度，提前预判是否会触顶；
2. 收到 429 后读取 Retry-After：按其指示的秒数等待窗口重置，等待结束后再重试；
3. 重试前确认幂等性：参考仓库中 sdk-tool-execution-retries.md 的说明——当前 Python SDK（0.16.0+）与 TypeScript SDK（0.14.0+）不会自动重试非幂等的工具执行（超时、限流或服务端错误后均不自动重试），因此对 send、create、update、delete 等操作，手动重试前应通过执行日志或 Provider 状态确认第一次请求是否真的未完成，避免重复写入；
4. 客户端缓存静态数据：工具定义（tool definitions）等不常变化的数据应在客户端缓存，避免反复请求消耗配额（官方 Best Practices 第 3 条）。

这套"限流感知"的节奏控制同样体现在仓库内部的 LLM 调用封装中：工作台生成的 Python 辅助代码（ts/packages/experimental/src/workbench/python-helpers.generated.ts）内置了 RATE_LIMIT_PATTERNS，可识别 rate limit、ratelimit、too many requests、quota exceeded、resource exhausted 等限流信号——这说明在真实的多 Provider 场景中，"限流"是一类需要显式识别并纳入退避策略的通用异常。

五、Provider 配额与组织配额是两套独立预算

组织级速率限制只是其中一层。Provider 侧的配额（例如 Google API 的配额限制）与 Composio 组织配额相互独立：即使 Composio 组织仍有充足容量，底层 Provider 的配额耗尽时，某个工具依然可能被限流或返回错误。

排障时必须区分两层限流：

• Composio 组织配额：体现在 X-RateLimit-* 与 Retry-After 响应头，按组织共享；
• Provider 配额：例如 Gmail、Google Sheets 等 Google API 的每日/每分钟配额，或 GitHub、Salesforce 等第三方 API 自身限流，与组织配额无关，也不会出现在 Composio 的限流头中。

遇到工具执行被节流时，先看错误来自哪一层：如果响应包含 Composio 的限流头，属于组织配额问题；如果错误信息指向 Provider（如 quota exceeded、resource exhausted），则应去 Provider 控制台核查对应 API 配额。

六、升级后仍触达旧上限：如何与支持团队协作

官方 KB 明确指出一个典型问题：组织升级套餐后，仍观察到旧的 2,000 次/分钟上限。此时不要盲目反复调用测试，而是按以下方式收集证据并与支持团队沟通：

1. 记录错误发生的时间点（error time）；
2. 保存该次请求的完整响应限流头（response rate-limit headers），即 X-RateLimit、X-RateLimit-Remaining、X-RateLimit-Window-Size、Retry-After 等；
3. 将时间与响应头一并提供给支持团队，用于核对配额生效状态与缓存刷新情况。

这两类信息是判断"配额是否真正切换"的关键证据，缺一不可。

七、限流相关能力速查

需求	做法	依据
查询当前套餐限额	查阅官方参考文档（docs/content/reference/rate-limits.mdx），以当前发布值为准	官方文档
跟踪窗口剩余量	每次响应读取 X-RateLimit-Remaining	KB 文章 + 参考文档
429 后何时重试	严格遵守 Retry-After	KB 文章 + 参考文档
减少无效请求	客户端缓存工具定义等静态数据	参考文档 Best Practices
判断是否重复执行	查执行日志与 Provider 状态，SDK 不自动重试非幂等操作	sdk-tool-execution-retries.md
升级后仍限流	提供错误时间 + 限流响应头给支持	KB 文章
平台侧错误识别	429 对应 rate_limited（42901）	api-error-extraction.test.ts

八、总结

Composio 的限流体系可以概括为三条主线：组织级共享的每分钟预算（Starter/Hobby 2,000、Growth/Pro 10,000、Enterprise 自定义）、通过响应头精确感知与优雅降级（X-RateLimit-* 跟踪余量、Retry-After 指导退避）、以及组织配额与 Provider 配额相分离的双层模型。实践中只需做到：引用套餐数值前核对官方文档、每次请求读取剩余量、429 后严格遵循 Retry-After、缓存静态数据减少无效调用，并在升级后遇到旧上限时及时携带时间戳与限流头联系支持——即可让 Agent 工作负载在配额之内稳定运行。