跳转到主要内容
速率限制在 Vercel Edge 运行时上通过 Upstash Redis 计数器进行强制执行。除特别说明外，所有限制均为60 秒滑动窗口。

​
默认公开 API 速率限制

范围限制窗口
按 IP（默认）600 次请求60 秒
适用于所有没有更严格覆盖规则的 /api/* 路由。由 api/_rate-limit.js / api/_ip-rate-limit.js 实现。

​
MCP 服务器

范围限制窗口
按 API 密钥（MCP 工具）60 次请求60 秒
详见 MCP。

​
按套餐的 API 速率限制

已认证的 REST API 密钥（wm_…）按账户而非按 IP 限制 —— 共享出口 IP 之后的某个密钥不会被其他租户的流量限流，且一个账户的所有密钥共享同一额度。
套餐每分钟（突发）每日包含超出每日额度之后
API Starter60 / 60 秒1,000 / UTC 日计量 —— 10,000 / 天硬停
API Business300 / 60 秒10,000 / UTC 日计量 —— 100,000 / 天硬停
Enterprise1,000 / 60 秒不限—
  • 每分钟是硬性突发限制 —— 超出会立即返回 429。
  • 每日包含是你的套餐额度；在 00:00 UTC 重置。超出部分是计量而非拒绝 —— 基于用量的超额计费正在推出。在此之前，一个安全上限（包含额度的 10 倍）会以 429 封顶失控用量。
  • 每分钟突发、每日额度和上限均为按账户（在一个账户的所有 wm_… 密钥间共享），因此签发更多密钥不会提高你的限制。（运维签发的 Enterprise 密钥是例外 —— 每个密钥独立限流。）
  • 需要更高限制？联系支持团队提升你套餐的额度。

​
OAuth 端点

端点限制窗口范围
POST /api/oauth/register560 秒按 IP
GET /api/oauth/authorize1060 秒按 IP
POST /api/oauth/token1060 秒按凭证 / 客户端 / IP 兜底
与 api/oauth/register.js、api/oauth/authorize.js 和 api/oauth/token.ts 中的实现保持一致。 对于 /api/oauth/token，限流器键在 client_credentials 下为 client_secret 哈希，其次为 client_id（若存在），仅当两个凭证标识均不可用时才回退到调用方 IP。 在 OAuth 流程中超过以上任一限制都会导致 MCP 客户端连接握手失败 — 请等待 60 秒后重试。

​
写入端点

端点限制窗口范围
POST /api/scenario/v1/run-scenario1060 秒按 IP
POST /api/scenario/v1/run-scenario（队列深度）100 在处理中—全局
POST /api/leads/v1/register-interest560 分钟按 IP + Turnstile（桌面来源需要签名 HMAC 绕过）
POST /api/leads/v1/submit-contact360 分钟按 IP + Turnstile
其他写入端点（/api/brief/share-url、/api/notification-channels、/api/create-checkout、/api/customer-portal 等）回退使用上面的默认按 IP 限制。

​
Bootstrap / 健康 / 版本

这些端点大多使用默认公开 API 限制。缓存头因端点而异：
  • GET /api/bootstrap — 浏览器 / 会话响应保留默认缓存策略：全键响应使用 Cache-Control: public, s-maxage=600, stale-while-revalidate=120, stale-if-error=900 加上 fast 层 CDN-Cache-Control；显式 ?tier=fast / ?tier=slow 请求使用浏览器 max-age=60 / max-age=300 和 CDN s-maxage=600 / s-maxage=7200。密钥认证响应使用 Cache-Control: no-store 且不发出 CDN 缓存头。用户 API 密钥校验还有一个故障关闭的固定 60 秒按 IP 预校验限制，最多 600 次尝试。
  • GET /api/health — private, no-store, max-age=0 加上 CDN-Cache-Control: no-store。
  • GET /api/version — public, s-maxage=300, stale-while-revalidate=60, stale-if-error=3600。

​
速率限制响应头（在 429 之前自我节流）

每个 /api/* 响应 —— 无论成功还是错误 —— 都会通告 IETF RateLimit 头字段，以便 agent 在触发 429 之前自行控制节奏： 
RateLimit-Policy: "default";q=600;w=60
RateLimit-Limit: 600
  • RateLimit-Policy —— 默认滑动窗口下 w 秒窗口内的适用额度（q）。更严格的按端点、按套餐和 OAuth 限制（见上表）适用于这些路由。
  • RateLimit-Limit —— 以裸整数形式给出的同一额度，供早于结构化字段草案的解析器使用。
这些是静态通告，因此不会在热路径上增加延迟。出于向后兼容，也会发出遗留的 X-RateLimit-* 名称。

​
被限制时的响应

HTTP 429 还会携带实时的每窗口计数器（remaining 为 0；reset 和 Retry-After 为增量秒数）以及组合的 RateLimit 成员： 
HTTP/1.1 429 Too Many Requests
RateLimit-Policy: "default";q=<limit>;w=<window>
RateLimit-Limit: <limit>
RateLimit-Remaining: 0
RateLimit-Reset: <seconds until reset>
RateLimit: "default";r=0;t=<seconds until reset>
Retry-After: <seconds>
X-RateLimit-Limit: <limit>
X-RateLimit-Remaining: 0
X-RateLimit-Reset: <reset, ms since epoch>
Content-Type: application/json

{ "error": "Too many requests" }
注意 IETF RateLimit-Reset（以及组合 RateLimit 成员中的 t 值）是剩余秒数，而遗留的 X-RateLimit-Reset 是以毫秒为单位的绝对纪元时间。对于每日上限的 429，Retry-After 倒计时到下一个 00:00 UTC。

​
重试指南

  • 遵守 Retry-After。不要在 429 上反复猛击。
  • 对于批量任务请控制节奏：默认按 IP 600 次/分钟，约为你提供 ~10 次/秒的余量。
  • 对于 MCP，60 次/分钟对对话式使用绰绰有余，但对脚本化批量抓取较为紧张 — 批量任务请优先使用 REST API。
  • 莫名其妙的 429 通常意味着你正在共享一个出口 IP（公司代理、CI runner）。如需提升按密钥的限制，请联系支持团队。

​
客户通知与付费套餐上限

API 与 MCP 套餐上限依据权益附带的产品目录限制进行跟踪：
套餐API 请求 / 天API 突发 / 分钟MCP 调用 / 天MCP 突发 / 分钟
Free0000
Pro005060
API Starter1,000601,00060
API Business10,00030010,000300
Enterprise不限1,000不限1,000
当付费用户接近或超过以上任一限制时，WorldMonitor 会记录一条精简的 Convex 汇总并在设置中开启一条当前账户通知。每日计数读取自同一治理强制执行的按账户计量器，因此警告反映的用量数值与套餐计量口径一致。每日限制在 80% 时警告，并在 100% 时切换为超限；突发限制仅在持续压力下通知，而非单次孤立尖峰。 若该通知仍然有效，一个由 Resend 支撑的生命周期流程会以有界节奏发送一封邮件。邮件与仪表盘通知会说明当前用量、相关套餐限制及可用选项：减少流量、等待重置、在存在自助路径时升级，或在下一层级非自助时联系支持。 WorldMonitor 不会因用户越过上限而自动升级、收取超额费用或将客户迁入 API Business。付费套餐的任何未来硬性强制执行必须先通过内部 apiPlanLimitNotices.getEnforcementReadiness 门控：无陈旧用量来源、无待处理 / 失败的邮件、且无被阻塞的自助升级路径。

​
硬上限（非软限制）

  • Webhook 回调 URL 必须为 HTTPS（localhost 除外）。
  • api/download 文件大小限制约为每请求 50 MB。
  • 当待处理队列超过 100 时，POST /api/scenario/v1/run-scenario 会全局暂停接收新作业 — 返回 429。
  • api/v2/shipping/webhooks 的 TTL 为 30 天 — 需重新注册以延长。