EXCEED_RATELIMIT

Encountering an error? Get help with AI tools

Error Cause

The request rate exceeds the limit and the request is rejected by the gateway (HTTP status code 429).

Possible types of rate limiting that can be triggered include:

1. Environment package rate limiting: The request rate exceeds the environment QPS quota of the purchased package;
2. Resource dimension rate limiting: The total resource QPS threshold configured for a single cloud function or cloud run service is exceeded;
3. Client dimension rate limiting: The request rate of a single client (user ID or client IP) to a resource exceeds the configured threshold;
4. Route dimension rate limiting: The total resource QPS or per-client QPS threshold configured on an HTTP gateway route is exceeded.

The last three types are custom rate limits configured in the console. For configuration instructions, see Rate Limiting Settings. For custom rate limiting, client dimension rate limiting is executed first, followed by resource (route) dimension rate limiting, to prevent a single client from consuming the entire resource quota.

You can determine which type of rate limiting blocked the request from the error message:

Error message	Type of rate limiting triggered
Environment xxx exceeds rate limit.	Environment package rate limiting
Resource xxx exceeds rate limit.	Resource dimension rate limiting (cloud function, cloud run) or route dimension rate limiting (HTTP gateway)
Client xxx exceeds rate limit.	Client dimension rate limiting

Solution

Environment package rate limiting

Upgrade package

You can choose a higher version package to increase QPS quota.

For QPS differences between packages, please see CloudBase Billing Documentation

Purchase promotion resource pack

If QPS needs temporary overrun, you can purchase daily promotion resource pack to increase. Promotion resource pack takes effect on the day of purchase.

For promotion resource pack pricing, please refer to CloudBase Billing Documentation/Promotion Resource Pack

Enable QPS overage billing

If your business has periodic traffic peaks, you can enable QPS overage billing and configure a higher QPS upper limit. See QPS Control.

Resource dimension rate limiting

1. Go to Rate Limiting Settings and increase the resource dimension threshold of the corresponding cloud function or cloud run service. The configurable range is 100 to the environment's maximum QPS;
2. If the environment's maximum QPS is already configured but still insufficient, first increase the environment QPS upper limit through QPS Control, and then adjust the resource dimension threshold;
3. If the growth is indeed normal business traffic, consider using a dedicated environment for high-load resources to avoid mutual interference.

Client dimension rate limiting

1. Go to Rate Limiting Settings and increase the client dimension threshold of the corresponding resource. The configurable range is 0 to 30 QPS;
2. If rate limiting is based on client IP, users behind a shared egress IP (corporate or campus network, NAT gateway, etc.) will be limited together. It is recommended to switch to rate limiting by user ID;
3. If rate limiting is based on user ID, requests need to carry a CloudBase user identity (accessToken). Requests without user identity cannot be resolved to a user ID and are allowed, bypassing rate limiting. When accessing through HTTP Gateway, you also need to enable Authentication on the corresponding route, otherwise requests do not carry user identity;
4. Check whether the traffic is abnormal, such as scripts scraping APIs, and add blocking logic at the application layer if necessary.

Self-managed proxy: pass X-Forwarded-For correctly

The Envoy in front of the CloudBase gateway uses the last hop IP in the X-Forwarded-For header as the real client IP. If requests pass through a self-managed proxy (Nginx, Ingress, API gateway, CDN, etc.) before reaching CloudBase, the proxy must set X-Forwarded-For correctly so that the last hop IP is the real client IP. Otherwise, the gateway treats the proxy or CDN node IP as the client IP, and all users behind that egress are identified as a single client and rate limited together.

Configuration notes:

• The proxy must append the IP of the peer that directly connects to it to the end of X-Forwarded-For, instead of overwriting the header;
• With multiple self-managed proxies, the rightmost IP of the X-Forwarded-For sent to CloudBase must still be the real client IP, which requires the innermost proxy to restore the real IP before appending;
• If X-Real-Ip is also set, make sure it is the real client IP as well (the gateway prefers this header).

Example 1: Nginx as the outermost proxy (directly facing clients)

location / {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  # Append the peer IP to the end
    proxy_set_header X-Real-Ip $remote_addr;                      # Optional, must be the real client IP
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass https://<your-upstream>;
}

If the client does not send X-Forwarded-For, the header value is real client IP. If the client forges the header, the value becomes forged IP, real client IP, and the last hop is still the real client IP.

Example 2: Multiple proxies / CDN origin pull

The innermost proxy (directly connected to CloudBase) restores the real client IP first and then appends it, ensuring the last hop is the real client IP:

# Only real IP related directives are listed
set_real_ip_from 10.0.0.0/8;        # Trusted upstream proxy or CDN origin CIDR
real_ip_header X-Forwarded-For;
real_ip_recursive on;               # $remote_addr is restored to the last untrusted IP, the real client IP

location / {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  # Append the restored $remote_addr
    proxy_pass https://<your-upstream>;
}

Example 3: Kubernetes Ingress-NGINX

data:
  enable-real-ip: "true"
  proxy-real-ip-cidr: "10.0.0.0/8"   # Trusted upstream (for example CLB) CIDR used to restore the real client IP
  compute-full-forwarded-for: "true" # Append the real client IP to the end of X-Forwarded-For

After configuration, print the x-forwarded-for header in your cloud function to verify that the last IP matches the public IP of the client that sends the request.

Route dimension rate limiting

1. In the rate limiting configuration of the corresponding HTTP gateway route, increase the total resource QPS or per-client QPS threshold;
2. If a large number of requests under the same route come from the same egress IP, you can appropriately relax the per-client threshold, or switch to rate limiting by user ID.

General recommendations

1. Rate limiting configuration changes take effect in about 1-2 minutes;
2. Clients are advised to implement exponential backoff retries for 429 responses to avoid continuously triggering rate limiting.