Rate Limits

API requests are rate-limited per API key. Every response includes rate limit headers.

Tiers

Tier	Rate Limit	Use Case
Free	100 requests / minute	Testing, personal projects
Pro	1,000 requests / minute	Production apps, automation, CI/CD
Team	10,000 requests / minute	Team plans (shared pooled limit across all members)

Response Headers

Every API response includes these headers:

Header	Description
X-RateLimit-Limit	Your tier's rate limit
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets

Upgrading to Pro Limits

After generating your API key, register it with your Pro subscription:

curl -X POST https://www.toolbox-kit.com/api/v1/register-key \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "tb_your_api_key_here",
    "subscriptionId": "YOUR_SUBSCRIPTION_ID",
    "provider": "dodo"
  }'

Handling Rate Limits

When you hit the rate limit, you'll receive a 429 status code. Use the X-RateLimit-Reset header to know when to retry:

async function callApi(endpoint, body) {
  const res = await fetch(`https://www.toolbox-kit.com/api/v1/${endpoint}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`,
    },
    body: JSON.stringify(body),
  });

  if (res.status === 429) {
    const resetAt = res.headers.get('X-RateLimit-Reset');
    const waitMs = (Number(resetAt) * 1000) - Date.now();
    await new Promise(r => setTimeout(r, Math.max(waitMs, 1000)));
    return callApi(endpoint, body); // retry
  }

  return res.json();
}