跳到主要内容

EXCEED_RATELIMIT

遇到错误？使用 AI 工具协助排查

错误原因​

请求速率超过限制，请求被网关拒绝（HTTP 状态码 429）。

可能触发的限频类型包括：

  1. 环境套餐限频：请求速率超过所购买套餐的环境 QPS 配额；
  2. 资源维度限频：为单个云函数或云托管服务配置的资源总 QPS 阈值被超过；
  3. 客户端维度限频：单个客户端（用户 ID 或客户端 IP）对某个资源的请求速率超过配置的阈值；
  4. 路由维度限频：HTTP 网关路由上配置的资源总 QPS 或单客户端 QPS 阈值被超过。

后三类属于用户在控制台配置的自定义限频，配置方式参考 限频设置。自定义限频会先执行客户端维度限频，再执行资源（路由）维度限频，以避免单个客户端占满整个资源的配额。

可根据错误信息判断请求被哪类限频拦截：

错误信息触发的限频类型
Environment xxx exceeds rate limit.环境套餐限频
Resource xxx exceeds rate limit.资源维度限频（云函数、云托管）或路由维度限频（HTTP 网关）
Client xxx exceeds rate limit.客户端维度限频

解决方案​

环境套餐限频​

升级套餐​

您可以选择更高版本的套餐，以提高 QPS 配额。

各套餐 QPS 区别请查看 云开发计费文档

购买大促资源包​

QPS 如需临时超限，可通过按天购买大促资源包提升。大促资源包购买后当天生效。

大促资源包价格请参考 云开发计费文档/大促资源包

开启 QPS 超限按量​

若业务存在周期性峰值，可开启 QPS 超限按量并配置更高的 QPS 上限，详见 QPS 控制。

资源维度限频​

  1. 前往 限频设置，提高对应云函数或云托管服务的资源维度阈值，可配置范围为 100 至环境最大 QPS；
  2. 若已配置为环境最大 QPS 仍不满足，可先通过 QPS 控制 提高环境 QPS 上限，再调整资源维度阈值；
  3. 若确为业务正常流量增长，建议为高负载资源拆分独立环境，避免相互影响。

客户端维度限频​

  1. 前往 限频设置，提高对应资源的客户端维度阈值，可配置范围为 0 至 30 QPS；
  2. 如果按客户端 IP 限频，共享出口 IP（公司或校园网络、NAT 网关等）下的用户会被一并限制，建议改为按用户 ID 限频；
  3. 如果按用户 ID 限频，请求需要携带云开发用户身份（accessToken），未携带用户身份的请求无法识别用户 ID，会被放通而不受限频约束；通过 HTTP 网关 访问时，还需要在对应路由上开启「身份认证」，否则请求不会携带用户身份；
  4. 排查是否为脚本刷接口等异常流量，必要时在应用层补充拦截逻辑。

自建代理场景：正确传递 X-Forwarded-For​

如果请求在到达云开发前经过了自建代理（Nginx、Ingress、API 网关、CDN 等），必须保证代理正确设置了 X-Forwarded-For，且最后一跳 IP 为真实客户端 IP。否则网关会把代理或 CDN 节点的 IP 当作客户端 IP，导致该出口下的所有用户被识别为同一个客户端，从而被整体限频。

配置要点：

  • 多级自建代理时，最终发给云开发的 X-Forwarded-For 最右侧仍须为真实客户端 IP，需要由最内层代理做 IP 还原后再追加；

示例一：Nginx 作为最外层代理（直接面对客户端）

location / {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  # 追加对端 IP 到末尾
    proxy_set_header X-Real-Ip $remote_addr;                      # 可选，值须为真实客户端 IP
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass https://<your-upstream>;
}

此时若客户端未携带 X-Forwarded-For，请求头即为 真实客户端IP；若客户端伪造了该请求头，则为 伪造IP, 真实客户端IP，最后一跳仍为真实客户端 IP。

示例二：多级代理 / CDN 回源

由最内层（与云开发直连的）代理先还原真实客户端 IP，再追加，保证最后一跳为真实客户端 IP：

# 仅列出与真实 IP 相关的配置
set_real_ip_from 10.0.0.0/8;        # 可信的上游代理或 CDN 回源网段
real_ip_header X-Forwarded-For;
real_ip_recursive on;               # $remote_addr 还原为最后一个不可信 IP，即真实客户端 IP

location / {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  # 追加还原后的 $remote_addr
    proxy_pass https://<your-upstream>;
}

示例三：Kubernetes Ingress-NGINX

data:
  enable-real-ip: "true"
  proxy-real-ip-cidr: "10.0.0.0/8"   # 可信上游（如 CLB）网段，用于还原真实客户端 IP
  compute-full-forwarded-for: "true" # 将真实客户端 IP 追加到 X-Forwarded-For 末尾

配置完成后，可在云函数中打印请求头 x-forwarded-for 进行验证，确认最后一个 IP 与发起请求的客户端公网 IP 一致。

路由维度限频​

  1. 在 HTTP 网关对应路由的限频配置中，提高资源总 QPS 或单客户端 QPS 阈值；
  2. 同一路由下若大量请求来自同一出口 IP，可适当放宽单客户端阈值，或改用按用户 ID 限频。

通用建议​

  1. 限频配置变更约 1-2 分钟生效；
  2. 客户端建议对 429 响应实现指数退避重试，避免持续触发限频。