---
title: "Check rate limits or refill tokens"
method: POST
path: "/limiter"
tags: ["Rate Limiting"]
---

# Check rate limits or refill tokens

`POST /limiter`

Use this endpoint to either:
- Check if a user or resource can proceed (`action: check`).
- Refill tokens for multiple resource keys (`action: refillTokens`).

The API will return `200` whether a user is allowed or rate limited. You'll be able to check whether the user was rate limited from the `result` property. A separate `429` is used only when the developer account reaches their quota, if any.

## Request body

- union
  - LimiterRequest
    - `userId` string, nullable — The ID of the user to rate limit. Used to keep track of users across requests.
    - `key` string, nullable — The key to identify your protected resource. Used to keep track of requests to the same resource.
    - `action` 'check' | 'refillTokens', required — Whether to completely refill one or multiple users' tokens (`refillTokens`) or check if the user can proceed with the request (`check`).
    - `limiters` object[], required — Up to 4 limiters of unique types to check against.
      - `type` 'fixed' | 'sliding' | 'token' | 'borrow'
      - `maxRequests` integer — if `type` is `fixed` or `sliding`, this must be supplied. It means the amount of requests the user can make in the given `interval`.
      - `interval` union — If `type` is `fixed` or `sliding`, this must be supplied. It means the amount of time before the `maxRequests` counter is reset. This is relative, and the final result is different based on `type`, check the full documentation for more details.
        - 'minute' | 'hour' | 'day'
        - number — The interval in seconds.
      - `tokensCost` number — if `type` is `token`, this must be supplied. It means the amount of tokens the current request will cost. If the user has less than this amount of tokens, they will be rate limited.
      - `tokensPerReplenish` number — if `type` is `token`, this must be supplied. It means the amount of tokens that will be replenished per `interval`.
      - `maxTokens` number — If `type` is `token`, this must be supplied. It means the amount of tokens the user starts with and the maximum amount they can accumulate.
      - `borrowAction` 'start' | 'end' — If `type` is `borrow`, this must supplied. It means whether to start or stop blocking requests for this borrow limiter.
      - `timeout` number — If `type` is `borrow`, this must be supplied. It means the timeout in seconds to reset the rate limiter if your code fails to end the borrow.
  - RefillRequest
    - `action` 'refillTokens', required — Must be set to `refillTokens`.
    - `keys` object[], nullable, required — A list of up to 100 keys to refill tokens for. If null, will refill the global key for the token limiter.
      - `key` string, nullable
      - `userId` string, nullable

## Response `200`

Request processed

- union
  - SuccessResult
    - `result` 'success', required
    - `message` string, required
    - `tokensLeft` number, nullable
  - LimitedResult
    - `result` 'limited', required
    - `message` string, required
    - `timeLeft` number, required — Time left in seconds until the user can make the next request without being rate limited. If multiple limiters are passed, this is time left for the longest limiter to reset.
    - `tokensLeft` number, nullable

## Other responses

- `400` — Invalid input
- `401` — Unauthorized - Missing or invalid API key
- `429` — Quota reached - Customer exceeded their allowed quota

## Changes

> 2 revisions in range; 1 could not be searched.

- **2026-03-27** `e2b1dd81c304` — 3 warning
  - added the new `MISSING_PARAMETERS` enum value to the `error` response property for the response status `400`
  - added the new `MISSING_PARAMETERS` enum value to the `error` response property for the response status `401`
  - added the new `MISSING_PARAMETERS` enum value to the `error` response property for the response status `429`

[Change history](https://skmtc.dev/borrowdev/apis/borrow-api-reference/changes/limiter/post.md)

---

[API](https://skmtc.dev/borrowdev/apis/borrow-api-reference.md) · [All operations](https://skmtc.dev/borrowdev/apis/borrow-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/borrowdev/borrow-api-reference/revisions/41d875ae782d/schema)