* feat: Rate limits refactoring * Process review comments * Add isolate_rate_limit? param to rate limit config * Fix tests * Ignore store_rate_limit_config if disabled api * Allow recaptcha headers in CORS * Tuning * Increase limits
4.3 KiB
Rate Limits Configuration
Rate limits can be defined in a JSON configuration file apps/block_scout_web/priv/rate_limit_config.json or passed to API_RATE_LIMIT_CONFIG_URL as a URL to the JSON file.
Configuration Structure
The JSON configuration is a map where:
- Keys: API endpoint paths
- Values: Rate limit configuration
Example Configuration
"api/account/v2/send_otp": {
"recaptcha_to_bypass_429": true,
"ip": {
"period": "1h",
"limit": 1
}
}
Path Rules
- Paths should not contain query parameters
- Paths should not contain trailing slashes
- Paths can contain:
*- Works as a wildcard (matches any path starting from the asterisk)- Example:
api/v2/*matchesapi/v2andapi/v2/addresses - ⚠️ Wildcard
*allowed only at the end of the path
- Example:
:param- Represents a variable parameter in the endpoint path- Example:
api/v2/addresses/:parammatchesapi/v2/addresses/0x00000..000
- Example:
- ⚠️ It's not allowed to use
*and:paramsimultaneously
Path Matching Priority
- Paths without
:paramand* - Paths with
:param - Paths with
*
Default Configuration
The config must contain a default key that defines the default API rate limit configuration. This will be used for endpoints that don't match any defined paths in the config.
Note
: GraphQL endpoints are out of scope for this config. Their rate limits are based on ENVs:
API_GRAPHQL_RATE_LIMIT_*
Rate Limit Options
Each rate limit entry can contain the following keys:
Rate Limit Methods
account_api_key- Allows using API key emitted in My AccountImportant
: When overriding
account_api_key, ensure your limits are much lower than the default oneswhitelisted_ip- Allows rate limiting by whitelisted IPstatic_api_key- Allows rate limiting by static API keytemporary_token- Allows rate limiting by temporary token (cookie) issued by/api/v2/keyip- Allows rate limiting by IP address
Additional Options
cost- Integer value used to decrease allowed limit (default:1)ignore- Iftrue, the endpoint won't be rate limitedrecaptcha_to_bypass_429- Iftrue, allows passing recaptcha header with response to bypass 429 errors.bypass_token_scope- Scope of recaptcha bypass token (currently only supportstoken_instance_refetch_metadata)isolate_rate_limit?- Iftrue, creates a separate rate limit bucket for this endpoint. Instead of using the shared rate limit key, it prepends the endpoint path to create an isolated bucket (e.g.,api/v2/address_127.0.0.1for the/api/v2/addressendpoint with IP-based rate limiting).
⚠️ It is recommended to use either recaptcha_to_bypass_429 or temporary_token, not both.
Rate Limit Option Values
Each rate limit method can have one of these values:
true- Rate limit option is allowed, limits pulled from ENVsfalseor omitted - Rate limit option is disabled- Map with configuration:
limit- Integer value representing max requests allowed per periodperiod- Rate limit time period in time format
ReCAPTCHA Implementation
ReCAPTCHA responses should be passed via headers:
recaptcha-v2-response- For V2 captcharecaptcha-v3-response- For V3 captcharecaptcha-bypass-token- For non-scoped bypass recaptcha tokenscoped-recaptcha-bypass-token- For scoped bypass recaptcha token (currently only supportstoken_instance_refetch_metadatascope)
Note
: ReCAPTCHA for
/api/v2/keyendpoint should be sent in the request body.
Rate Limit Headers
The backend returns informational headers:
X-RateLimit-Limit- Total limit per timeframeX-RateLimit-Remaining- Remaining requests within current time windowX-RateLimit-Reset- Time to reset rate limits in milliseconds
These headers may return -1 in case of:
- Internal errors
API_NO_RATE_LIMIT_API_KEYis used- Rate limits are disabled on the backend
- The endpoint has
"ignore": trueparameter set
Bypass Options Header
The bypass-429-option header indicates how to bypass rate limits:
recaptcha- Use ReCAPTCHA response in headerstemporary_token- Get temporary cookie from/api/v2/keyendpointno_bypass- No way to bypass 429 error