Sign in

v66

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

Apply multiple rate limit checks

Check and enforce multiple rate limits in a single request for any identifiers (user IDs, IP addresses, API clients, etc.).

Use this to efficiently check multiple rate limits at once. Each rate limit check is independent and returns its own result with a top-level passed indicator showing if all checks succeeded.

Response Codes: Rate limit checks return HTTP 200 regardless of whether limits are exceeded — check the passed field to see if all limits passed, or the success field in each individual result. 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 all specific namespaces being checked)
post/v2/ratelimit.multiLimit

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

All rate limit checks completed successfully. Check the success field in each result to determine if the corresponding request is allowed.

Example response

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