速率限制

速率限制按 API 密钥以固定 60 秒窗口执行，并在窗口边界重置。默认每个密钥每分钟 60 次请求；Production 可协商更高上限。

响应头

每个响应都包含当前速率限制状态。

超过限制时，响应为 HTTP 429，包含 error.code = rate_limit_exceeded 以及给出等待秒数的 Retry-After 响应头。

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1782604860
Retry-After: 12

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "已超过请求频率限制。",
    "request_id": "req_..."
  }
}

公开（未身份验证）路由

公开路由没有 API 密钥，因此按客户端 IP 每分钟限制 20 次请求，并使用相同的固定窗口、响应头和 429 + Retry-After 约定。该限制适用于申请创建、状态与批准领取（POST /v1/partner-applications*）以及 POST /v1/api-keys/bootstrap，以抑制垃圾申请和批准令牌暴力破解。

退避指南

• 遵守 Retry-After。等待指定秒数后再重试，不要持续冲击端点。
• 对于重复的 429 和 5xx 响应，请使用带抖动的指数退避。
• 主动限流。跟踪 X-RateLimit-Remaining，并在其归零前降低速率。
• 尽可能批处理。使用 POST /events/batch 一次发送最多 500 个事件，而不是多次调用 POST /events（事件 API）。
• 按工作负载分离密钥。限制按密钥计算，因此高容量摄取和交互调用应使用不同密钥。
• 受支持的幂等操作可安全重试。事件按 event_id 去重；创建播放令牌、创建授权请求和轮换密钥接受 X-NU-Request-Id。24 小时内已完成的重试会重放原始结果；处理中重复请求返回 409 conflict。

Production 速率限制处理属于 Production 检查清单。