API Rate Limits for Email Lookups: Plan, Batch and Retry

API rate limits decide how fast you can run an email lookup job, and they catch many teams by surprise. A script that works on ten rows can fail on ten thousand because the API starts rejecting calls. This guide explains how rate limits work, what Tomba's limits are by plan, and how to batch, pace and retry so a large job finishes.

What are API rate limits?#

An API rate limit caps how many requests you can send in a given time. Providers set them to keep the service fair and stable. When you go over, the server answers with HTTP status 429, "Too Many Requests", which RFC 6585 defines for this case.

Limits usually come in layers: per second, per minute and per day. You can hit any one of them. A script can stay under the per-second cap and still run out of daily requests.

What are Tomba's API rate limits?#

The Tomba API lists limits by plan as requests per second, per minute and per day. Authentication uses two headers, X-Tomba-Key and X-Tomba-Secret, against the base URL https://api.tomba.io/v1.

For the search, finder, similar and technology endpoints:

For the email verifier:

Pro Plus, Scale and credit packs of 50,000 or more have no limit on these endpoints. Enterprise has no per-second or per-minute limit and allows 100,000 requests a day. Daily limits reset at 00:00 UTC. You can ask the API for the limits on your own account with GET /v1/rate-limits. Always trust the live numbers over this table, since plans change.

How do you plan a large lookup job?#

Do the maths before you start. Take the number of rows and divide it by the lowest limit that applies.

For example, 3,000 finder lookups on a plan with a 500 per day limit need at least six days. Per second limits matter too: at 3 requests per second, 3,000 calls need about 1,000 seconds if nothing else slows you down.

If the numbers do not fit, you have three choices: spread the work over days, move to a plan with higher limits, or use bulk jobs. Bulk tasks have their own limits and are built for large files.

How to stay under API rate limits in code#

1. Throttle on your side. Add a small delay between calls so you stay under the per-second cap. A queue with a fixed rate is better than a loop.
2. Limit concurrency. Ten parallel workers each sending as fast as they can will break a 3 per second cap.
3. Track the daily total. Count requests and stop before the daily limit. Resume after 00:00 UTC.
4. Skip repeats. Cache results by input. Re-asking for the same name and domain wastes a request.
5. Filter first. Remove rows without a domain, and duplicates, before you call anything.

How to retry after a 429#

When a request fails with 429, do not retry at once. Use exponential backoff:

1. Wait a short time, for example one second.
2. Retry. If it fails again, double the wait.
3. Add a little random jitter so many workers do not retry together.
4. Stop after a fixed number of attempts and log the row for a later pass.

If the response carries a Retry-After header, honour it. Check your actual responses, since not every API sends one.

A 200 response can still mean there is no result. Keep "no result" separate from "error" in your logs, so you do not retry rows that simply have no data.

How do credits relate to rate limits?#

They are separate. Rate limits control speed. Credits control volume and cost. Tomba's finder costs 1 search credit when it returns an address, and a verification costs 1 verification credit. Search and verification credits are separate balances. You can run out of credits well before you hit a rate limit, or the other way round.

For Tomba's phone validator, errors and 429 responses cost nothing, according to the product page. Check each endpoint's page for its own charging rules.

Using the MCP server or add-ins#

Tomba's MCP server has no limit of its own, but the calls it makes count toward your plan's API limits. The Excel and Airtable add-ins space their requests to stay within your plan. If a job uses either, you do not need to write retry code. For code-based jobs, see the Tomba CLI and the API docs.

Checklist before a big run#

• Count rows and compare with daily limits.
• Test 20 rows and confirm the output.
• Deduplicate and drop rows with no domain.
• Add throttling, backoff and logging.
• Verify the emails you found with the Tomba Email Verifier before you send.

Frequently asked questions#

What does HTTP 429 mean?#

It means too many requests. Slow down and retry later.

Do rate limits reset?#

Daily limits reset at 00:00 UTC. Per-second and per-minute limits recover as time passes.

How can I see my own limits?#

Call GET /v1/rate-limits, according to the Tomba API page.

Are limits the same for every endpoint?#

No. The verifier has its own table. Bulk jobs also have their own limits.

Next step#

Work out your numbers, add a throttle, and start with a small batch using the Tomba Email Finder.