Rate limits protect an API from overload and keep one noisy client from degrading service for everyone. For a verification API they also protect the number supply, since every order reserves a real resource. Knowing how limits work lets you design traffic that never hits them.
Types of limits you will meet
- Requests per second controls short bursts.
- Requests per minute or hour controls sustained use.
- Concurrent open orders caps how many numbers you hold at once.
- Per endpoint limits are stricter on expensive calls such as order creation than on cheap status reads.
Read the signals the server gives you
A 429 response often includes a retry-after value in seconds, and sometimes headers that show your remaining quota and reset time. Prefer those exact values over guesses. If no hint is present, fall back to exponential backoff.
Token bucket on the client
Do not wait for the server to say no. A client-side token bucket spends one token per request and refills at a steady rate. When the bucket is empty, requests wait in a queue. This smooths bursts and keeps you comfortably below the limit.
bucket = TokenBucket(rate=5, capacity=10)
await bucket.take() # waits if empty
response = await client.create_order(...)Backoff with jitter
After a 429 or 503, wait, then try again. Double the wait after each failure up to a cap, and randomise the delay. Without jitter, every client that failed at the same instant retries at the same instant, and the spike repeats.
Prioritise your queue
Not all requests are equal. A user staring at a spinner during signup outranks a nightly reconciliation job. Use separate queues or a priority field so background work yields first when capacity is tight.
Avoid wasteful polling
The most common cause of limit trouble is aggressive status polling. Poll every few seconds with a gentle increase in interval, stop at the order deadline, and prefer webhooks where available. Polling a hundred orders every second is a hundred requests per second for no benefit.
Monitor your own usage
Track requests per minute, 429 rate and queue depth. If 429 responses exceed one percent of calls, you are tuned too close to the edge. Raise the limit through your account contact, or reduce demand through batching and caching of catalogue data.
Good rate handling is invisible to users. They simply see their code arrive, while your client quietly paces itself.
Frequently asked questions
What is a safe starting rate?
Start at half of the documented limit and increase while watching the share of 429 responses. If limits are not documented, begin at a few requests per second and ask the provider for guidance before a large launch or batch job.
Does retry-after override my backoff?
Yes. When the server tells you exactly how long to wait, use that value, perhaps plus a small random amount. Your own exponential schedule is the fallback for responses that carry no hint.
Are limits per key or per account?
It varies, so check the documentation. If limits are per account, several keys will not help and may hide the problem. Share a single client-side limiter across your services so total traffic stays inside the budget.
How do I handle limits across many servers?
Share the budget. Either divide the limit evenly among instances, or use a central limiter such as a shared counter in a fast data store. Without coordination, ten servers each staying under the limit together exceed it. Re-check the split whenever you add or remove instances, and keep a safety margin.
Put it into practice
Start from the services page and pick the service and country you need. Developers can find endpoints and examples in the API documentation. Learn who we are on the about page, find troubleshooting steps in the help center, or send a question through the contact form. The blog has further reading. When you are set, open the verification dashboard.
Related reading: Scaling Verification Traffic for Product Launches and Handling API Error Codes in Verification Workflows.
