Sign in

v66

OpenAPI 3.1.0raw.githubusercontent.com2026-08-0174265626.3 KB
ratelimit

Set ratelimit override

Create or update a custom rate limit for specific identifiers, bypassing the namespace default.

Use this to create premium tiers with higher limits, apply stricter limits to specific users, or implement emergency throttling.

Important: Overrides take effect immediately and completely replace the default limit for matching identifiers. Use wildcard patterns (e.g., premium_*) to match multiple identifiers.

Permissions: Requires ratelimit.*.set_override or ratelimit.<namespace_id>.set_override

post/v2/ratelimit.setOverride

Request body

namespacestring required

The ID or name of the rate limit namespace.

durationinteger required

The duration in milliseconds for the rate limit window. This defines how long the rate limit counter accumulates before resetting to zero.

Considerations:

  • This can differ from the default duration for the namespace
  • Longer durations create stricter limits that take longer to reset
  • Shorter durations allow more frequent bursts of activity
  • Common values: 60000 (1 minute), 3600000 (1 hour), 86400000 (1 day)
identifierstring required

Identifier of the entity receiving this custom rate limit. This can be:

  • A specific user ID for individual custom limits
  • An IP address for location-based rules
  • An email domain for organization-wide policies
  • Any other string that identifies the target entity

Wildcards (*) can be used to create pattern-matching rules that apply to multiple identifiers. For example:

  • 'premium_*' would match all identifiers starting with 'premium_'
  • '*_admin' would match all identifiers ending with '_admin'
  • 'suspicious' would match any identifier containing 'suspicious'

More detailed information on wildcard pattern rules is available at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules

limitinteger required

The maximum number of requests allowed for this override. This defines the custom quota for the specified identifier(s).

Special values:

  • Higher than default: For premium or trusted entities
  • Lower than default: For suspicious or abusive entities
  • 0: To completely block access (useful for ban implementation)

This limit entirely replaces the default limit for matching identifiers.

Response

Override successfully created or updated and is now active.

Example response

{
  "meta": {
    "requestId": "req_123"
  }
}