Rate limits

We apply two independent throttling layers on top of your monthly plan quota:

Per-API-key rate limit — protects our infrastructure (CPU, DB, queue)
Plan quota — your billing budget, see Pricing

Both must be satisfied for a request to succeed.

Per-endpoint rate limits

Endpoint	Limit	Window
`POST /api/v1/validate`	120 req	1 minute
`POST /api/v1/validate-async`	20 req	1 minute
`GET /api/v1/credits`	60 req	1 minute
`GET /api/v1/batch/{id}`	unlimited	—
`POST /api/v1/demo` (no API key)	3 req	24h / IP
`POST /dashboard/playground` (UI)	30 req	1 minute

The default for validate is 120 / minute but can be raised on Enterprise / Custom plans on request.

Response headers

Every rate-limited response includes the standard X-RateLimit-* headers:

X-RateLimit-Limit:      120
X-RateLimit-Remaining:  117
X-RateLimit-Reset:      1714850460   (Unix timestamp)

When you exceed the rate limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 17

{
  "error": "rate_limited"
}

The Retry-After header tells you how many seconds to wait before retrying.

Rate limit vs quota — the difference

	Rate limit	Plan quota
Scope	per API key, per minute	per user, per month
Trigger	bursts of traffic	total monthly usage
Status code	`429 rate_limited`	`402 quota_exceeded`
How to fix	wait, then retry	upgrade plan or wait next cycle

Hitting the rate limit doesn't consume credits; the request never reached the validator. Hitting the quota does count as 1 credit (request was processed before the cap was checked). Edit: incorrect — quota is checked before validation, so quota_exceeded responses don't consume credits either.

Bulk patterns

If you need to validate thousands of numbers, don't burst the sync /validate endpoint. Use the async batch instead:

# DON'T : 10,000 sync calls = ~84 minutes due to rate limit
for phone in "${phones[@]}"; do
  curl ... /api/v1/validate -d "{\"phone\":\"$phone\"}"
done

# DO : 1 async batch = a few seconds latency
curl ... /api/v1/validate-async -d "{\"phones\":[...]}"

The async endpoint accepts up to 10,000 numbers per batch and processes them in the background, all within a single rate-limit slot.

Internal bulk bypass

If you call /api/v1/validate from inside a bulk handler with the X-Internal-Bulk-Token header (only valid in our own worker), the per-call rate limit is bypassed. This is documented for completeness — you cannot use this header from outside.

Distributed clients

Each API key has its own rate-limit bucket. If you need to scale beyond 120 req/min from multiple workers, create multiple API keys and distribute the load. There's no penalty for having many keys — they all draw from the same monthly quota.