# 频率限制

Source: https://docs.simail.ai/zh/rate-limits/

> API、MCP、WebSocket、注册和控制台的请求频率限制,以及如何处理 429 和 Retry-After。

频率限制用来挡住失控的循环和滥用。能收发多少邮件的配额在[用量、限额与熔断](/zh/limits/)。

## API 与 MCP

| 项目 | 限制 | 计数单位 |
|---|---|---|
| 带 API key 的请求(REST 和 MCP) | 每分钟 600 次(突发) | key |
| 不带 key 的请求 | 每分钟 120 次 | IP 地址 |
| 每天的 API 调用 | 按套餐 | 组织 |
| `POST /v0/agent/sign-up` | 每个网段每小时 10 次。被拒的码还会让注册在本小时剩余时间暂停:按网络运营商(同一 ASN 每小时 50 次被拒)和全局(所有来源每小时 200 次);暂停时回 `503` 并带 `Retry-After`。最近一次成功注册在 7 天内、且本小时没有被拒码的网段不受暂停影响 | 网段 / ASN / 全局 |
| `POST /v0/waitlist` | 每个网段每天 5 次,每个网络运营商每天 50 次,另有全局每日上限 | 网段 / ASN |
| MCP OAuth 客户端注册 | 每天 10 次 | 网段 |
| WebSocket | 每个组织 50 个连接,每个 key 10 个,每分钟 10 次握手,每个连接 1 小时 | 组织 / key |
| Webhook 投递 | 每分钟 60 次(超出的延后,从不丢弃) | 端点 |

网段指 IPv4 /24 或 IPv6 /48。突发限制在离你最近的节点执行,是近似值;按天的配额是精确的。

## 控制台(人)

| 项目 | 限制 |
|---|---|
| 发送邮件登录验证码 | 每个「邮箱 + 网段」组合每 15 分钟 3 次、每天 10 次;同一邮箱不分网段每天合计 30 次;每个网段每小时 20 次 |
| 验证码尝试 | 每个验证码 3 次;每个网段每小时 30 次验证 |
| 验证码失败 | 同一网段每小时失败 10 次,会把这个地址在这个网段的验证码登录锁一小时;来自任何地方的失败每小时累计 50 次,会把这个地址锁一小时。passkey 登录永远不会被锁。 |
| 再次验证的验证码 | 按会话计:每会话每 15 分钟发 3 次、每天 10 次(每个网段每小时 20 次,与登录分开计);每个验证码尝试 3 次;每小时失败 10 次,会把这个会话的再次验证码锁一小时 |
| 添加或删除 passkey | 每个用户每天 5 次 |
| 兑换邀请码 | 每个用户每小时 5 次,每个 IP 每小时 20 次;连续失败 5 次锁定兑换一小时 |
| 控制台请求 | 已登录会话每会话每分钟 300 次;没有会话时每个网段每分钟 60 次(带会话 cookie 的请求先过每个网段每分钟 600 次的宽松检查) |

响应从不透露某个邮箱是否注册过:无论是否注册,限额和提示都一样。

## 处理 `429`

每个 `429` 都带 `Retry-After` 请求头(秒),以及 `retryable: true` 的 problem+json 正文:

```json
{
  "type": "https://docs.simail.ai/errors#rate_limited",
  "title": "RateLimitedError",
  "status": 429,
  "code": "rate_limited",
  "message": "Too many requests.",
  "fix": "Wait for Retry-After seconds, then retry.",
  "retryable": true,
  "request_id": "req_…"
}
```

- 至少等 `Retry-After` 秒,再重发**同一个**请求(发信要用同一个 `Idempotency-Key`)。
- 再次碰到限制时,加随机抖动并指数退避。
- 不要把负载分到更多 key 上来绕过限制;真正起作用的限制是按组织计的。
- 用事件([拉取](/zh/events/)、[webhook](/zh/webhooks/)、[WebSocket](/zh/realtime/))代替对邮件的紧密轮询。

`429 daily_limit_exceeded` 表示每日配额用完,不是突发限制:`Retry-After` 指向下一个时间窗。