Docs/Rate Limits

Rate Limits

Understand how API rate limiting works, tier limits by subscription plan, and per-key overrides.

Token Bucket Algorithm

Rate limits use a sliding 60-second window backed by Redis. Each request is timestamped; requests older than the window are discarded. When the count exceeds your tier limit, the API returns HTTP 429.

Rate Limit Tiers

Limits are determined by your subscription type. All authenticated requests share a single bucket per user.

Tier	Requests / Minute	Bucket Key	Notes
Anonymous	5	IP address	Unauthenticated requests
Free	10	User ID	Free plan accounts
Trial	30	User ID	Trial subscription accounts
Pro	100	User ID	Pro subscription accounts
Admin	1,000	User ID	Admin accounts

Per-Key Override

Each API key has a rateLimit field (requests per minute, default 100). When set, this value overrides the subscription tier limit for requests authenticated with that key.

Configure per-key limits in the API Keys dashboard or when creating a key via the management API.

Override applies only to requests using that specific API key
Other keys on the same account continue using tier defaults unless overridden
Organization-level apiRateLimit applies to org-managed keys

Response Headers

Every API response includes rate limit headers so you can track usage in real time.

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining before the limit is reached
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait before retrying (429 responses only)

Check Your Rate Limit Status

Query your current rate limit status at any time:

GET /rate-limit

curl https://api.rocketverifier.com/rate-limit \
  -H "Authorization: Bearer rv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "tier": "pro",
  "subscription_type": "pro",
  "limit": 100,
  "remaining": 85,
  "used": 15,
  "reset_at": 1704672000
}

429 Error Response

429

Rate Limit Exceeded

{
  "success": false,
  "error": "Rate limit exceeded. Please try again later.",
  "limit": 100,
  "reset_at": "2024-01-08T10:30:00+00:00"
}

Best Practices

Respect Retry-After

When you receive a 429, wait at least the number of seconds in the Retry-After header before sending another request. Our SDKs handle this automatically.

Use batch endpoints for bulk work

Instead of verifying thousands of emails one-by-one, submit a batch job via POST /v1/verify/batch. Batch jobs count as a single API call to start.

Monitor headers proactively

Track X-RateLimit-Remaining in your integration and throttle requests before hitting the limit to avoid failed calls.

Need Higher Limits?

Pro and Enterprise plans include higher rate limits. Contact us for custom throughput on high-volume workloads.

View error codes →