---
title: "Set ratelimit override"
method: POST
path: "/v2/ratelimit.setOverride"
tags: ["ratelimit"]
---

# Set ratelimit override

`POST /v2/ratelimit.setOverride`

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`

## Request body

- V2RatelimitSetOverrideRequestBody — Sets a new or overwrites an existing rate limit override. Overrides allow you to apply special rate limit rules to specific identifiers, providing custom limits that differ from the default. Overrides are useful for: - Granting higher limits to premium users or trusted partners - Implementing stricter limits for suspicious or abusive users - Creating tiered access levels with different quotas - Implementing temporary rate limit adjustments - Prioritizing important clients with higher limits
  - `namespace` string, required — The ID or name of the rate limit namespace.
  - `duration` integer, 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)
  - `identifier` string, 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
  - `limit` integer, 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 `200`

Override successfully created or updated and is now active.

- V2RatelimitSetOverrideResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` V2RatelimitSetOverrideResponseData, required
    - `overrideId` string, required — The unique identifier for the newly created or updated rate limit override. This ID can be used to: - Reference this specific override in subsequent API calls - Delete or modify this override later - Track which override is being applied in rate limit responses - Associate override effects with specific rules in analytics Store this ID if you need to manage the override in the future.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - Insufficient permissions (requires `ratelimit.*.set_override`)
- `404` — Not Found - Namespace not found
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/versions/fa78aafac89c/schema)