---
title: "Apply multiple rate limit checks"
method: POST
path: "/v2/ratelimit.multiLimit"
tags: ["ratelimit"]
---

# Apply multiple rate limit checks

`POST /v2/ratelimit.multiLimit`

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)

## Request body

- V2RatelimitLimitRequestBody[] — Array of rate limit checks to perform
  - `namespace` string, required — The id or name of the namespace.
  - `cost` integer — 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.
  - `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.
  - `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.
  - `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 `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.

## Response `200`

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

- V2RatelimitMultiLimitResponseBody
  - `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` V2RatelimitMultiLimitResponseData, required — Container for multi-limit rate limit check results
    - `passed` boolean, required — Overall success indicator for all rate limit checks. This is true if ALL individual rate limit checks passed (all have success: true), and false if ANY check failed. Use this as a quick indicator to determine if the request should proceed.
    - `limits` V2RatelimitMultiLimitCheck[], required — Array of individual rate limit check results, one for each rate limit check in the request
      - `namespace` string, required — The namespace this rate limit result corresponds to. Use this field to correlate the response with the request when checking multiple rate limits.
      - `identifier` string, required — The identifier this rate limit result corresponds to. Use this field to correlate the response with the request when checking multiple rate limits.
      - `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.
      - `passed` 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

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `410` — Gone - Namespace has been deleted
- `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)