Copy page

Platform

Rate limits

Tomba limits how many requests you can send to each endpoint per second, per minute, and per day. The limits depend on your plan and apply to your whole account. Monthly allowances are separate; see Credits and usage.

Limits by plan

Each cell is requests per second / per minute / per day.

Other plans:

• Pro Plus and Scale plans: no limits on these endpoints.
• Enterprise: no per-second or per-minute limit, and 100,000 requests per endpoint per day.
• Credit packs: while a pack has credits left, each limit is the higher of your plan's and the pack's. A pack of 50,000 credits or more removes the limits.

The table shows each plan's standard limits. GET /v1/rate-limits returns the limits that apply to your account; see Check your limits.

Endpoints with fixed limits

These endpoints have the same limits on every plan:

Leads, lead lists, lead attributes, /logs, /usage, /rate-limits, and /domain-status aren't rate-limited.

How limits are counted

• One set of counters per account. Every API key, OAuth app, and workspace member of an account shares the same counters. Limits aren't per key.
• Per endpoint. Each row in the table has its own counters.
• Every accepted request counts, including requests that return no result or fail after the limit check. Requests rejected with 429 don't count.
• Daily limits reset at 00:00 UTC.
• Per-second and per-minute limits reset once 1 second or 60 seconds pass without an accepted request. A steady stream of requests keeps the counter from resetting, so continuous traffic can reach the limit even when its average rate is lower. After a 429 for rps or rpm, pause for the whole window, 1 or 60 seconds, before you retry.

Rate limit headers

Every response from an endpoint in the Limits by plan table carries these headers, on successful and 429 responses alike:

On a 429, the headers show the values from before the rejected request.

Endpoints with fixed limits return X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on successful responses and only Retry-After on a 429.

Handle 429 responses

A request over a limit fails with status 429, error type rate_limit, and a Retry-After header in seconds:

Code
{
    "errors": {
        "type": "rate_limit",
        "message": "Rate limit exceeded (rpm). Limit is 150 requests. Retry after 42 seconds.",
        "code": 429
    }
}

The message names the limit that was hit: rps, rpm, or daily. For daily, Retry-After is the time until 00:00 UTC. A 429 without Retry-After from email count, email format, location, or email sources means that balance is used up, not that you're sending too fast; see Credits and usage.

Wait at least Retry-After seconds, and for rps and rpm at least the whole window, then retry with exponential backoff:

Check your limits

GET /v1/rate-limits returns the limits that apply to your account and your current usage, for each endpoint group. It isn't rate-limited itself.

Code
curl "https://api.tomba.io/v1/rate-limits" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY"

Code
{
    "data": {
        "domain-search": {
            "limits": { "rps": 8, "rpm": 150, "daily": 4000 },
            "usage": { "rpm_used": 12, "daily_used": 847 }
        },
        "email-verifier": {
            "limits": { "rps": 5, "rpm": 100, "daily": 4000 },
            "usage": { "rpm_used": 0, "daily_used": 230 }
        }
    }
}

Most keys match the endpoint path. The others:

In a workspace, members see the owner's limits and the workspace's combined usage. The dashboard shows the same information under Rate limits.