Skip to main content

​
POST /v2/ratelimit.limit

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)

​
Request

​
namespace
string
required
The id or name of the namespace. Namespaces organize rate limits by feature or resource type (e.g., sms.sign_up, api.requests).
  • Must be 1-255 characters long
Example: sms.sign_up
​
identifier
string
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.
  • Must be 1-255 characters long
Example: user_12345
​
limit
integer
required
Sets the maximum operations allowed within the duration window before requests are rejected. When this limit is reached, subsequent requests fail with success: false 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.
  • Minimum: 1
  • Maximum: 1,000,000
Example: 1000
​
duration
integer
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.
  • Minimum: 1000 (1 second)
  • Maximum: 2,592,000,000 (30 days)
Example: 60000
​
cost
integer
default:"1"
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.
  • Minimum: 0
  • Maximum: 1000
Example: 5

​
Response

​
limit
integer
required
The maximum number of operations allowed within the time window. This reflects either the default limit specified in the request or an override limit if one exists for this identifier.This value helps clients understand their total quota for the current window.
​
remaining
integer
required
The number of operations remaining in the current window before the rate limit is exceeded. Applications should use this value to:
  • Implement client-side throttling before hitting limits
  • Display usage information to end users
  • Trigger alerts when approaching limits
  • Adjust request patterns based on available capacity
When this reaches zero, requests will be rejected until the window resets.
​
reset
integer
required
The Unix timestamp in milliseconds when the rate limit window will reset and ‘remaining’ will return to ‘limit’.This timestamp enables clients to:
  • Calculate and display wait times to users
  • Implement intelligent retry mechanisms
  • Schedule requests to resume after the reset
  • Implement exponential backoff when needed
The reset time is based on a sliding window from the first request in the current window.
​
success
boolean
required
Whether the request passed the rate limit check. If true, the request is allowed to proceed. If false, the request has exceeded the rate limit and should be blocked or rejected.You MUST check this field to determine if the request should proceed, as the endpoint always returns HTTP 200 even when rate limited.
​
overrideId
string
If a rate limit override was applied for this identifier, this field contains the ID of the override that was used. Empty when no override is in effect.This can be useful for:
  • Debugging which override rule was matched
  • Tracking the effects of specific overrides
  • Understanding why limits differ from default values

​
Example

cURL
curl -X POST https://api.unkey.com/v2/ratelimit.limit \
  -H "Authorization: Bearer <your-root-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "api.requests",
    "identifier": "user_abc123",
    "limit": 100,
    "duration": 60000
  }'
Response (Allowed)
{
  "meta": {
    "requestId": "req_01H9TQPP77V5E48E9SH0BG0ZQX"
  },
  "data": {
    "limit": 100,
    "remaining": 99,
    "reset": 1714582980000,
    "success": true
  }
}
Response (Rate Limited)
{
  "meta": {
    "requestId": "req_01H9TQPP77V5E48E9SH0BG0ZQY"
  },
  "data": {
    "limit": 100,
    "remaining": 0,
    "reset": 1714582980000,
    "success": false
  }
}

​
Error Codes

  • 400 - Bad request (invalid parameters)
  • 401 - Unauthorized (missing or invalid root key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not found (namespace does not exist)
  • 410 - Gone (namespace has been deleted)
  • 429 - Too many requests (workspace rate limit exceeded)
  • 500 - Internal server error

Build docs developers (and LLMs) love

Get started for freeTalk to us