Getting Started

Rate Limits

Leadron enforces two layers of limits: a per-IP gateway throttle on all traffic, and a monthly API call quota per tenant when authenticating with an API key. Exceeding either returns 429 Too Many Requests.

Per billing period

API key quotas reset when your subscription renews

Per-IP throttle

1,000 requests per 15 minutes at the gateway

Headers included

Responses include X-RateLimit-* and X-API-Usage-* headers

Gateway Rate Limit

All API traffic passes through a shared gateway throttle scoped by client IP address. This limit applies equally across every plan tier and is independent of your monthly API key quota.

Scope	Limit	Window
Per IP address	1,000 requests	15 minutes

Monthly API Call Limits by Plan

When you authenticate with an API key, usage is tracked against your subscription plan's monthly quota. Counters reset at the start of each billing period (not on a calendar month boundary). When the quota is reached, API key requests return 429 until the next billing cycle.

Plan	Plan ID	API Calls / Billing Period
Free	free	5,000
Growth	growth	50,000
Scale	scale	200,000
Enterprise	enterprise	999,999

Usage headers

API key responses include X-API-Usage-Used, X-API-Usage-Limit, and X-API-Usage-Remaining headers to track consumption for the current billing period.

Response Headers

Gateway throttling and API key usage are exposed via response headers so you can monitor consumption and implement backoff before hitting a hard limit.

Example response headers (API key request on Growth plan)

http

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1738942060
X-API-Usage-Used: 12450
X-API-Usage-Limit: 50000
X-API-Usage-Remaining: 37550

Header	Description
X-RateLimit-Limit	Maximum gateway requests allowed per IP in the current window
X-RateLimit-Remaining	Gateway requests remaining for this IP in the current window
X-RateLimit-Reset	Unix timestamp when the gateway rate limit window resets
X-API-Usage-Used	API key calls consumed in the current billing period (API key auth only)
X-API-Usage-Limit	API call quota for your plan in the current billing period
X-API-Usage-Remaining	API key calls remaining in the current billing period

429 Too Many Requests

A 429 can mean the gateway IP throttle or your plan's API call quota was exceeded. Check the response body and headers to determine which limit was hit.

Response429Too Many Requests

Gateway IP throttle exceeded

429 Response

json

{
  "success": false,
  "status": 429,
  "message": "Too many requests",
  "retryAfter": 842
}

Response429Too Many Requests

Monthly API call quota exceeded (API key auth)

429 Response

json

{
  "success": false,
  "status": 429,
  "code": "API_LIMIT_EXCEEDED",
  "message": "API call limit exceeded for your current billing period",
  "used": 50001,
  "limit": 50000
}

Exponential backoff

When you receive 429, use the response retryAfter field (gateway throttle) or wait until your billing period renews (API quota). Implement exponential backoff with jitter for sustained high-volume usage.

Best Practices

Monitor X-API-Usage-Remaining and throttle before your billing-period quota is exhausted
Monitor X-RateLimit-Remaining to stay under the gateway IP throttle
Use batch endpoints where available to reduce request count
Cache responses when appropriate (e.g. plans, configuration)
Implement exponential backoff with jitter when retrying after 429
Contact support for custom limits on Enterprise plans