Overview

SaaS Custom Domains now offers a powerful Rate Limiting feature that allows you to control the flow of requests to your upstreams and custom domains. This guide will walk you through the process of setting up rate limits and explain their benefits to your services.

Benefits of Rate Limiting

Prevent Abuse: Protect your APIs and services from excessive use or potential attacks.
Ensure Fair Usage: Maintain equitable access to resources for all users.
Improve Stability: Prevent traffic spikes from overwhelming your systems.
Cost Control: Reduce expenses associated with handling excessive requests.
Enhanced Security: Mitigate the risk of DDoS attacks and brute force attempts.

Setting Up Rate Limits

Rate limits can be configured at two levels:

Upstream level
Custom domain level

To set up a rate limit, follow these steps:

Log in to your SaaS Custom Domains account.
Navigate to the Rate Limiting section for either your upstream or custom domain.
Click on the "Create Rate Limit" button.
In the "Create Rate Limit" form:
- Select the Rate Limit Type from the dropdown.
- Specify the number of requests allowed and the time period (e.g., 120 requests every 30 seconds).
- Choose the key parts for the rate limit. IP Address is always included and cannot be removed.
- Optionally, add additional key parts: Domain Host, Path, Query String, or Authorization Header.
Click Create Rate Limit to apply the settings.

How Rate Limiting Works

When a rate limit is reached, SaaS Custom Domains will return a 429 status code (Too Many Requests) to the client. This is a standard HTTP status code that indicates the user has sent too many requests in a given amount of time. It's important to handle this status code gracefully in your applications and inform your users when they've hit a rate limit.

Upstream vs Custom Domain Rate Limits

When setting up rate limits, it's important to understand how they are applied across your upstream and custom domains. If you create a rate limit for an upstream, this limit will apply to all custom domains associated with that upstream by default.

However, if you then create a specific rate limit for a particular custom domain under that upstream, the custom domain's rate limit will take precedence. In other words, for that specific custom domain, we'll only use its own rate limit and not the upstream one.

This allows you to have a general rate limit for most of your domains via the upstream setting, while still maintaining the flexibility to set more specific or different limits for particular domains as needed.

This approach provides a balance between broad protection and granular control over your rate limiting strategy.

Key Parts Explained

The "key" in rate limiting refers to the unique identifier used to track and limit requests. It's essentially a combination of one or more pieces of information from the request that, when combined, create a unique signature for that request or group of requests. The rate limit is then applied to all requests sharing the same key.

For example, if you set up a rate limit using only the IP Address as the key, the key might look like this: 203.0.113.195. All requests coming from this IP address would be counted towards the same rate limit. If you add more parts to the key, it becomes more specific.

For instance, a key combining IP Address and Path might look like this: 203.0.113.195:/api/users, which would apply a separate limit to requests to the /api/users path from that specific IP.

Here's a breakdown of the available key parts:

IP Address: Always included and cannot be removed. Limits requests based on the origin IP address. This is useful for preventing a single client from overwhelming your service. Example key: 203.0.113.195
Domain Host: Useful for multi-tenant applications to set different limits for different domains. This allows you to have separate rate limits for each domain your service handles. Example key: 203.0.113.195:example.com
Path: Apply specific limits to certain API endpoints or resources. This is helpful when you want to protect particular parts of your application that might be more resource-intensive or sensitive. Example key: 203.0.113.195:/api/high-load-endpoint
Query String: Differentiate rate limits based on query parameters. This can be useful for APIs that change behavior significantly based on query parameters. Example key: 203.0.113.195:/api/search?q=rate+limiting
Authorization Header: Ideal for authenticated requests, allowing per-user rate limiting. This is particularly useful for SaaS applications with different usage tiers or to prevent abuse of individual accounts. Example key: 203.0.113.195:Bearer_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

By combining these key parts, you can create very specific and flexible rate limiting rules. For instance, a key that combines IP Address, Path, and Authorization Header might look like this:

203.0.113.195:/api/posts:Bearer_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

This would allow you to set a rate limit for a specific user (identified by the Authorization Header) accessing a specific endpoint (/api/posts) from a particular IP address.

Use Case: Rate Limiting Authenticated Users

Here's how you can use the Authorization Header to set rate limits for individual authenticated users:

When creating a rate limit, select "Authorization Header" as an additional key part.
Set your desired limit, for example, 100 requests per minute.
Ensure your application includes a unique identifier for each user in the Authorization header of each request.

With this configuration:

Each unique user (identified by their Authorization header) will be limited to 100 requests per minute.
This limit is separate from the IP address limit, allowing you to have both global (IP-based) and per-user limits.
If a user exceeds their limit, only that specific user will be rate-limited, not all traffic from their IP address.

This approach is particularly useful for:

SaaS applications with tiered usage plans
APIs that need to ensure fair usage across all authenticated clients
Preventing abuse of user accounts in case of compromised credentials

Remember to inform your users about these limits and provide documentation on handling rate limit errors in their applications.

Best Practices

Start with conservative limits and adjust based on observed usage patterns.
Use different key parts to control the granularity of your rate limits.
Communicate rate limits to your users and provide guidance on handling rate limit errors.
Regularly review and adjust your rate limits to ensure they align with your application's growth and user needs.

That's it! You now know everything about Rate Limiting with SaaS Custom Domains.

Until next time, keep building!

Need more help? Reach out via the Intercom chat widget and we'll be right with you!