Rate limits

BotShield limits requests per credential. Each key type has several windows (called buckets), and a request is blocked when any one of them is full. A blocked request gets HTTP 403 with code: "RATE_LIMITED". It does not get HTTP 429, and there is no Retry-After header, so your client has to read the response body.

Limits by key type

Every operation call made with a credential counts once against that credential. Limits are per key, not per organization, so two API keys have separate counters.

Credential	Bucket	Limit
Development API key `bs_dev_…` and test site key `pk_test_…`	`burst`	30 requests per 10 seconds
	`hourly`	300 requests per hour
	`daily`	2,000 requests per day
Production API key `bs_production_…` and grant token `bss_…`	`per_minute`	60 requests per minute
	`hourly`	2,000 requests per hour
	`daily`	25,000 requests per day
Live site key `pk_live_…`	`per_minute`	120 requests per minute
	`daily`	25,000 requests per day
	`per_ip`	20 requests per minute from one IP address

Development limits are sized for building and testing. They are deliberately too low to run production traffic on a development key. The per_ip bucket on live site keys counts each visitor’s IP address separately. One visitor who hammers your page reaches it long before your key-wide limits are affected. Agent keys (bs_agent_…) have no published limit. Build your agent as if one applies: use the long-poll on GET /agentlink/check-status (wait_seconds up to 25) instead of a tight polling loop, and reuse a request_id when you retry a proposal. If your production traffic needs higher limits, contact BotShield. Limits can be raised for a specific key.

The blocked response

{
  "errors": [
    {
      "message": "Rate limit exceeded. Bucket \"burst\" hit its cap; retry in 7s.",
      "code": "RATE_LIMITED"
    }
  ],
  "_rateLimit": {
    "scope": "dev",
    "primary": { "bucket": "burst", "limit": 30, "remaining": 0, "resetIn": 7 },
    "buckets": {
      "burst": { "limit": 30, "remaining": 0, "resetIn": 7 },
      "hourly": { "limit": 300, "remaining": 212, "resetIn": 1841 },
      "daily": { "limit": 2000, "remaining": 1704, "resetIn": 50112 }
    }
  }
}

Field	Type	Description
`errors[0].code`	string	Always `RATE_LIMITED`. Test this value, not the HTTP status, because other errors also use 403 inside `data.error`.
`errors[0].message`	string	Names the bucket that is full and the seconds until it resets.
`_rateLimit.scope`	string	A label for the set of limits that applied to your key. Treat it as opaque.
`_rateLimit.primary`	object	The bucket closest to its limit. On a blocked request this is the bucket that blocked you.
`_rateLimit.primary.resetIn`	integer	Seconds until that bucket resets. Wait this long before you retry.
`_rateLimit.buckets`	object	Every bucket for your key, each with `limit`, `remaining`, and `resetIn` (seconds).

The blocked request did not run. Nothing was created or consumed, so it is safe to send again after the wait.

Watch your usage

Successful responses carry the same _rateLimit object next to data, so you can slow down before you are blocked:

{
  "data": {
    "data": {
      "anchor_grant_token": "bss_4b1e…",
      "anchor_grant_expires_in_seconds": 300,
      "organization": { "id": "org_…", "environment": "development" }
    }
  },
  "_rateLimit": {
    "scope": "dev",
    "primary": { "bucket": "burst", "limit": 30, "remaining": 22, "resetIn": 6 },
    "buckets": {
      "burst": { "limit": 30, "remaining": 22, "resetIn": 6 },
      "hourly": { "limit": 300, "remaining": 251, "resetIn": 1841 },
      "daily": { "limit": 2000, "remaining": 1743, "resetIn": 50112 }
    }
  }
}

The example is shortened. The data part is the operation’s normal response.

For API keys, test site keys, and grant tokens, _rateLimit is on every response.
For live site keys (pk_live_…), successful responses leave it out to keep browser traffic small. Send the header x-botshield-include-ratelimit: true to include it. A blocked response always includes it.

curl -s https://api.botshield.ai/operations/sdk/create-session \
  -H "Authorization: Bearer pk_live_…" \
  -H "Origin: https://www.meridianairlines.example" \
  -H "x-botshield-include-ratelimit: true" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '._rateLimit.primary'

Back off and retry

Wait for _rateLimit.primary.resetIn seconds, add a little random jitter so parallel workers do not all retry together, and cap the number of attempts.

type RateLimitedBody = {
  errors?: { message: string; code?: string }[];
  _rateLimit?: { primary?: { resetIn?: number } };
};

export async function fetchWithBackoff(
  input: string,
  init: RequestInit,
  maxAttempts = 4,
): Promise<Response> {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(input, init);
    if (response.status !== 403) return response;

    const body = (await response.clone().json().catch(() => ({}))) as RateLimitedBody;
    if (body.errors?.[0]?.code !== "RATE_LIMITED" || attempt >= maxAttempts) return response;

    // Wait for the bucket to reset, plus jitter so parallel workers do not retry together.
    const resetIn = body._rateLimit?.primary?.resetIn ?? 2 ** attempt;
    const delayMs = Math.min(resetIn, 60) * 1000 + Math.random() * 500;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }
}

If the full bucket is hourly or daily, resetIn is long. Do not hold a user’s request open for it. Return an error to your caller, alert your team, and look for the cause.

The TypeScript SDK’s built-in retry does not cover rate limits. Its default retry codes are 429 and 5xx, and a rate-limited call throws a BotShieldDefaultError with statusCode 403. Catch it and back off yourself. See TypeScript SDK.

Stay under the limits

Create sessions on demand. Call POST /sdk/create-session when a user is about to verify, not on every page load. Each session also leads to a create-verification-link call.
Poll at a steady pace. When you poll GET /verification/status from your server, every 2 to 3 seconds is enough. A request lives five minutes.
Use the long-poll for Agents Ask. One check-status call with wait_seconds=25 replaces a dozen short polls.
Use webhooks for outcomes you do not need instantly. See Webhooks overview.
Keep development and production apart. Load tests against a development key hit the development limits quickly.

Next steps

Errors

All error shapes and a typed unwrap helper.

API overview

Credentials and the response envelope.

Keys and environments

Which key belongs where.

Testing

Try a gate in Development.

Overview

BotShield Gate

Agents Ask

Limits by key type

The blocked response

Watch your usage

Back off and retry

Stay under the limits

Next steps

Errors

API overview

Keys and environments

Testing

​Limits by key type

​The blocked response

​Watch your usage

​Back off and retry

​Stay under the limits

​Next steps

Errors

API overview

Keys and environments

Testing

Limits by key type

The blocked response

Watch your usage

Back off and retry

Stay under the limits

Next steps