Apply rate limiting

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)

1 min read

post/v2/ratelimit.limit

Request example

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v2"
	"github.com/unkeyed/sdks/api/go/v2/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := s.Ratelimit.Limit(ctx, components.V2RatelimitLimitRequestBody{
        Namespace: "api.requests",
        Cost: unkey.Pointer[int64](5),
        Duration: 60000,
        Identifier: "user_abc123",
        Limit: 100,
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2RatelimitLimitResponseBody != nil {
        // handle response
    }
}

Response

{
  "data": {
    "limit": 100,
    "remaining": 99,
    "reset": 1714582980000,
    "success": true
  },
  "meta": {
    "requestId": "req_01H9TQPP77V5E48E9SH0BG0ZQX"
  }
}

post/v2/ratelimit.limit

Authorization

Authorizationstringheaderrequired#

Unkey uses bearer tokens for authentication. Public integrations use root keys, while the dashboard proxy uses short-lived JWTs.
To authenticate, include the token in the Authorization header of each request:

Authorization: Bearer unkey_123

Root keys have specific permissions attached to them, controlling what operations they can perform. Legacy permissions use tuple strings like api.*.create_key; resource permissions use Unkey Resource Names plus actions, like unkey:v1:ws_123:keyspaces/*#create_key.
Security best practices:

Keep root keys secure and never expose them in client-side code
Use different root keys for different environments
Rotate keys periodically, especially after team member departures
Create keys with minimal necessary permissions following least privilege principle
Monitor key usage with audit logs.

Body

application/json

namespacestringrequired#

The id or name of the namespace.

Length: 1–512

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.

Default: 1

Range: >= 0

durationintegerrequired#

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.

Range: 1000–2592000000

identifierstringrequired#

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.

Length: 1–512

limitintegerrequired#

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.

Range: >= 1

Responses

application/json

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

metaobjectrequired#

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.

Show child attributes

requestIdstringrequired#

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.

dataobjectrequired#

Show child attributes

limitintegerrequired#

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.

remainingintegerrequired#

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.

resetintegerrequired#

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.

successbooleanrequired#

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.

overrideIdstring#

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

metaobjectrequired#

Show child attributes

requestIdstringrequired#

errorobjectrequired#

Base error structure following Problem Details for HTTP APIs (RFC 7807). This provides a standardized way to carry machine-readable details of errors in HTTP response content.

Show child attributes

detailstringrequired#

A human-readable explanation specific to this occurrence of the problem. This provides detailed information about what went wrong and potential remediation steps. The message is intended to be helpful for developers troubleshooting the issue.

statusintegerrequired#

HTTP status code that corresponds to this error. This will match the status code in the HTTP response. Common codes include 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), and 500 (Internal Server Error).

titlestringrequired#

A short, human-readable summary of the problem type. This remains constant from occurrence to occurrence of the same problem and should be used for programmatic handling.

typestringrequired#

A URI reference that identifies the problem type. This provides a stable identifier for the error that can be used for documentation lookups and programmatic error handling. When followed, this URI should provide human-readable documentation for the problem type.

errorsobject[]required#

List of individual validation errors that occurred in the request. Each error provides specific details about what failed validation, where the error occurred in the request, and suggestions for fixing it. This granular information helps developers quickly identify and resolve multiple issues in a single request without having to make repeated API calls.

Show child attributes

locationstringrequired#

JSON path indicating exactly where in the request the error occurred. This helps pinpoint the problematic field or parameter. Examples include:

'body.name' (field in request body)
'body.items[3].tags' (nested array element)
'path.apiId' (path parameter)
'query.limit' (query parameter)
Use this location to identify exactly which part of your request needs correction.

messagestringrequired#

Detailed error message explaining what validation rule was violated. This provides specific information about why the field or parameter was rejected, such as format errors, invalid values, or constraint violations.

fixstring#

A human-readable suggestion describing how to fix the error. This provides practical guidance on what changes would satisfy the validation requirements. Not all validation errors include fix suggestions, but when present, they offer specific remediation advice.

Get ratelimit override List ratelimit overrides