Unkey · Schema

RatelimitRequest

API KeysRate LimitingAuthenticationDeveloper PlatformAccess ControlIdentityAnalytics

Properties

Name Type Description
name string The name of this rate limit. This name is used to identify which limit to check during key verification. Best practices for limit names: - Use descriptive, semantic names like 'api_requests', 'heavy_o
limit integer The maximum number of operations allowed within the specified time window. When this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit shoul
duration integer The duration for each ratelimit window in milliseconds. This controls how long the rate limit counter accumulates before resetting. Common values include: - 1000 (1 second): For strict per-second limi
autoApply boolean Whether this ratelimit should be automatically applied when verifying a key.
View JSON Schema on GitHub

JSON Schema

unkey-ratelimitrequest-schema.json Raw ↑ 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/RatelimitRequest",
  "title": "RatelimitRequest",
  "type": "object",
  "required": [
    "name",
    "limit",
    "duration",
    "autoApply"
  ],
  "properties": {
    "name": {
      "description": "The name of this rate limit. This name is used to identify which limit to check during key verification.\n\nBest practices for limit names:\n- Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'\n- Be consistent with naming conventions across your application\n- Create separate limits for different resource types or operation costs\n- Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')\n\nYou will reference this exact name when verifying keys to check against this specific limit.",
      "type": "string",
      "example": "api",
      "minLength": 3,
      "maxLength": 128
    },
    "limit": {
      "description": "The maximum number of operations allowed within the specified time window.\n\nWhen this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:\n- Your infrastructure capacity and scaling limitations\n- Fair usage expectations for your service\n- Different tier levels for various user types\n- The relative cost of the operations being limited\n\nHigher values allow more frequent access but may impact service performance.",
      "type": "integer",
      "format": "int64",
      "minimum": 1
    },
    "duration": {
      "description": "The duration for each ratelimit window in milliseconds.\n\nThis controls how long the rate limit counter accumulates before resetting. Common values include:\n- 1000 (1 second): For strict per-second limits on high-frequency operations\n- 60000 (1 minute): For moderate API usage control\n- 3600000 (1 hour): For less frequent but costly operations\n- 86400000 (24 hours): For daily quotas\n\nShorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion.",
      "type": "integer",
      "format": "int64",
      "minimum": 1000
    },
    "autoApply": {
      "description": "Whether this ratelimit should be automatically applied when verifying a key.",
      "type": "boolean",
      "default": false
    }
  }
}