Unkey · Schema

V2RatelimitLimitRequestBody

API KeysRate LimitingAuthenticationDeveloper PlatformAccess ControlIdentityAnalytics

Properties

Name	Type	Description
namespace	string	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
duration	integer	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 60
identifier	string	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, n
limit	integer	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 u

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/V2RatelimitLimitRequestBody",
  "title": "V2RatelimitLimitRequestBody",
  "additionalProperties": false,
  "properties": {
    "namespace": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "The id or name of the namespace.",
      "example": "sms.sign_up"
    },
    "cost": {
      "type": "integer",
      "format": "int64",
      "minimum": 0,
      "default": 1,
      "description": "Sets how much of the rate limit quota this request consumes, enabling weighted rate limiting.\nUse higher values for resource-intensive operations and 0 for tracking without limiting.\nWhen accumulated cost exceeds the limit within the duration window, subsequent requests are rejected.\nEssential for implementing fair usage policies and preventing resource abuse through expensive operations.\n",
      "example": 5
    },
    "duration": {
      "type": "integer",
      "format": "int64",
      "minimum": 1000,
      "maximum": 2592000000,
      "description": "Sets the rate limit window duration in milliseconds after which the counter resets.\nShorter durations enable faster recovery but may be less effective against sustained abuse.\nCommon values include 60000 (1 minute), 3600000 (1 hour), and 86400000 (24 hours).\nBalance user experience with protection needs when choosing window sizes.\n",
      "example": 60000
    },
    "identifier": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Defines the scope of rate limiting by identifying the entity being limited.\nUse user IDs for per-user limits, IP addresses for anonymous limiting, or API key IDs for per-key limits.\nAccepts letters, numbers, underscores, dots, colons, slashes, and hyphens for flexible identifier formats.\nThe same identifier can be used across different namespaces to apply multiple rate limit types.\nChoose identifiers that provide appropriate granularity for your rate limiting strategy.\n",
      "example": "user_12345"
    },
    "limit": {
      "type": "integer",
      "format": "int64",
      "minimum": 1,
      "description": "Sets the maximum operations allowed within the duration window before requests are rejected.\nWhen this limit is reached, subsequent requests fail with `RATE_LIMITED` until the window resets.\nBalance user experience with resource protection when setting limits for different user tiers.\nConsider system capacity, business requirements, and fair usage policies in limit determination.\n",
      "example": 1000
    }
  },
  "required": [
    "namespace",
    "identifier",
    "limit",
    "duration"
  ],
  "type": "object"
}