Copy page

Rate Limiting

Rate Limiting

Rate limiting controls how many requests a client can make to your API within a given time window. It protects your backend from traffic spikes, enforces fair usage across consumers, and enables tiered access for different customer plans.

Zuplo's rate limiter uses a sliding window algorithm enforced globally across all edge locations. When a client exceeds the limit, they receive a 429 Too Many Requests response with a Retry-After header indicating when they can retry.

Choosing your approach

Pick a rateLimitBy mode and a policy based on what your API looks like today. If you are not sure, start from the first row that matches and read the linked guide.

Use case	rateLimitBy	Policy	Learn more
Public API with no authentication	ip	Rate Limiting	Getting Started
Authenticated API, same limit for every consumer	user	Rate Limiting	Combining Policies
Tiered limits (free, pro, enterprise) from API key metadata	function	Rate Limiting with a custom function	Dynamic Rate Limiting
Tiered limits sourced from a database	function	Rate Limiting with a custom function	Per-user limits with a database
Single global cap on an expensive endpoint	all	Rate Limiting	How rate limiting works
Usage-based pricing counting multiple resources per request	user	Complex Rate Limiting (enterprise)	How rate limiting works

Policies

Zuplo provides two rate limiting policies.

The Rate Limiting policy enforces a single request counter per time window. Use it when you need a straightforward "X requests per Y minutes" limit.

The Complex Rate Limiting policy supports multiple named counters in a single policy, each tracking a different resource or unit of work. Use it for usage-based pricing where different endpoints consume different amounts of a resource. This policy requires an enterprise plan.

Dynamic rate limiting

Static rate limits apply the same threshold to every caller. With dynamic rate limiting, you provide a custom TypeScript function that determines limits at request time — so premium customers get higher throughput, free-tier users get a lower ceiling, and internal services can bypass limits entirely.

• Dynamic Rate Limiting guide — Implement custom rate limit functions
• Per-user rate limiting with a database — Advanced example using database lookups and the ZoneCache

Rate limiting and monetization

If you use Zuplo's Monetization feature, the monetization policy handles quota enforcement based on subscription plans. You can still add a rate limiting policy to provide per-second or per-minute spike protection on top of monthly billing quotas. These serve different purposes:

• Monetization quotas enforce monthly or billing-period usage limits tied to a subscription plan
• Rate limiting protects against short-duration traffic spikes that could overwhelm your backend

Recommended reading order

If you are new to rate limiting in Zuplo, read these pages in order. Each one builds on the previous.

1. Getting Started — Add a basic IP-based rate limit to an existing project and confirm it works end to end.
2. How rate limiting works — Learn what the sliding window algorithm does, what each rateLimitBy mode means, and which configuration options are available.
3. Combining Policies — Stack multiple limits on the same route and combine rate limiting with quotas or monetization.
4. Dynamic Rate Limiting — Vary limits per caller by writing a small TypeScript function.
5. Monitoring and Troubleshooting — Observe limits in production and diagnose unexpected behaviour.

Reference material to bookmark:

• Rate Limiting policy reference — Every configuration option for the standard policy.
• Complex Rate Limiting policy reference — Multi-counter configuration (enterprise).
• Rate Limit Exceeded error — What a 429 response looks like and how to debug unexpected ones.