UNunkeyed
ratelimit

Apply rate limiting

Changed on

Check and enforce rate limits for any identifier (user ID, IP address, API client, etc.).

Use this for rate limiting beyond API keys - limit users by ID, IPs by address, or any custom identifier. Supports namespace organization, variable costs, and custom overrides.

Response Codes: Rate limit checks return HTTP 200 regardless of whether the limit is exceeded — check the success field in the response to determine if the request should be allowed. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.

Required Permissions

Your root key must have one of the following permissions:

  • ratelimit.*.limit (to check limits in any namespace)
  • ratelimit.<namespace_id>.limit (to check limits in a specific namespace)
post/v2/ratelimit.limit

Request

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/ratelimit.limit
  • Auth
    HTTP bearer

Request body

namespacestring required

The id or name of the namespace.

costinteger

Sets how much of the rate limit quota this request consumes, enabling weighted rate limiting. Use higher values for resource-intensive operations and 0 for tracking without limiting. When accumulated cost exceeds the limit within the duration window, subsequent requests are rejected. Essential for implementing fair usage policies and preventing resource abuse through expensive operations.

durationinteger required

Sets the rate limit window duration in milliseconds after which the counter resets. Shorter durations enable faster recovery but may be less effective against sustained abuse. Common values include 60000 (1 minute), 3600000 (1 hour), and 86400000 (24 hours). Balance user experience with protection needs when choosing window sizes.

identifierstring required

Defines the scope of rate limiting by identifying the entity being limited. Use user IDs for per-user limits, IP addresses for anonymous limiting, or API key IDs for per-key limits. Accepts letters, numbers, underscores, dots, colons, slashes, and hyphens for flexible identifier formats. The same identifier can be used across different namespaces to apply multiple rate limit types. Choose identifiers that provide appropriate granularity for your rate limiting strategy.

limitinteger required

Sets the maximum operations allowed within the duration window before requests are rejected. When this limit is reached, subsequent requests fail with RATE_LIMITED until the window resets. Balance user experience with resource protection when setting limits for different user tiers. Consider system capacity, business requirements, and fair usage policies in limit determination.

Example request

{
  "namespace": "sms.sign_up",
  "cost": 5,
  "duration": 60000,
  "identifier": "user_12345",
  "limit": 1000
}

Response

Rate limit check completed successfully. Check the success field to determine if the request is allowed.

Example response

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

Changes

  • 89f6a753ffaeRevision changes
    • info

      the request property's maxLength was increased from 255 to 512

    • info

      the request property's maxLength was increased from 255 to 512

  • 43ad1ce9a152Revision changes
    • info

      the endpoint scheme security bearer was added to the API

    • info

      the endpoint scheme security rootKey was removed from the API