Rate limits

The three limits

Unit cost per endpoint

Each call charges its endpoint cost against the daily unit budget. /v1/find costs more than /v1/sources because it fans out to many shards and merges/dedupes the results.

For mixed traffic, work the math against units. Example: 1,000 find calls + 2,000 validate calls = 2,000 + 6,000 = 8,000 units, leaving 2,000 in the budget.

Headers on every response

Every authenticated response carries enough state to pace yourself without guessing. Read these on every response and back off proactively rather than reactively.

X-RateLimit-Burst:                60
X-RateLimit-Refill-Per-Sec:        1
X-RateLimit-Tokens-Remaining:     59
X-RateLimit-Daily-Units-Limit: 10000
X-RateLimit-Daily-Units-Used:     22
X-RateLimit-Concurrent-Limit:      8
X-RateLimit-Concurrent-Now:        1
X-Endpoint-Cost-Units:             2

• X-RateLimit-Tokens-Remaining - current bucket level. Drops by X-Endpoint-Cost-Units on each call, refills at refill-per-sec.
• X-RateLimit-Daily-Units-Used / Limit - your unit budget position for the day. Resets at UTC midnight.
• X-RateLimit-Concurrent-Now / Limit - in-flight requests across your account. Use this to size your own client-side concurrency.
• X-Endpoint-Cost-Units - what THIS specific call cost in units. Useful when the table above lags a pricing change.

When you exceed

429 with a Retry-After header in seconds. The body tells you which limit you hit so you can decide whether to wait, slow down, or rebalance.

HTTP 429 Too Many Requests
Retry-After: 4

{
  "error": "rate_limited",
  "detail": "Token bucket empty. Retry in 4 seconds.",
  "reason": "minute_burst_exceeded",
  "retry_after": 4
}

• minute_burst_exceeded - token bucket empty. Wait retry_after seconds for refill.
• daily_units_exhausted - account-wide unit budget gone. Resets at UTC midnight; retry_after is the seconds until reset.
• concurrency_exceeded - 8 in-flight already. retry_after=1; immediate retry usually fine after one in-flight call returns.
• key_daily_units_exhausted - only fires if you set a per-key sub-allocation lower than your account cap. Account budget may still have room.

Throughput examples

• Pure search: 5,000 /v1/find calls/day. With limit=500 that's up to 2.5M rows/day per account.
• Pure validation: 3,333 /v1/email/validate calls/day before the unit budget runs out.
• Sustained pace: at 60 burst + 1/sec refill, you can hold ~60 req/min steady, with a burst-of-60 in the first second of an idle bucket.
• Parallelism: 8 concurrent calls. A worker pool of 8 keeps the gateway saturated without ever 429ing on concurrency.