Quota tiers
Named rate-limit plans - define Bronze, Silver and Gold once and assign them to any number of API clients.
Overview
A quota tier is a named, reusable set of rate limiting rules. Instead of configuring the same limits on each security definition one by one, you define the limits once, give them a name - Bronze, Silver, Gold - and assign that name to as many API clients as needed. Changing the plan in one place updates every client that references it, immediately and without restarts.
Counting stays per consumer - two definitions on the same Gold tier each get the full Gold allowance with their own counters - and clients see their allowance through the X-RateLimit-Limit and X-RateLimit-Remaining response headers.
Tiers are managed in the dashboard under Security > Quota tiers.
Definition fields
| Field | Notes |
|---|---|
| Name | A unique name for the tier - the name definitions and groups reference |
| Description | Optional free-form text describing the plan |
| Rules | One or more rules, each with an address list and time ranges holding rate, burst, limit and time unit - the same rule builder as for rate limiting |
The tier list shows each tier's limits at a glance along with how many definitions and groups reference it - a tier that is still referenced cannot be deleted.
Tiers are exported and imported with enmasse under the top-level quota_tier key, and definitions and groups reference them by name through a quota_tier entry - the fields are in the enmasse reference.
Security definitions and channels
Open the Rate limiting link of a Basic Auth or API key definition, or of a REST or SOAP channel. At the top of the page there are two tabs:
- Quota tier - pick a tier from the select and the definition or channel follows the tier's rules
- Custom rules - the definition or channel has its own rules, edited in place
A definition or channel either references a tier or has its own rules - never both. Both levels still stack - a request must pass the security definition's tier or rules first and the channel's tier or rules next.
Security groups
A tier set on a security group applies to every member of that group, again with per-member counting. In the group's create or edit dialog, pick the tier from the Quota tier select.
Precedence, from strongest to weakest:
- A definition's own custom rules
- A tier assigned directly to the definition
- A tier assigned to a group that the definition belongs to
Response headers
Requests governed by a consumer's limits receive the X-RateLimit-Limit and X-RateLimit-Remaining headers, and an exhausted allowance answers with 429 and Retry-After - the details, including the header semantics and the full request flow, are under quota tiers in the administration guide.