Copy page

Get started

Going to production

Work through each section before you send production traffic to the Tomba API. Each item links to the page that defines the behavior.

Timeouts

• Set your HTTP client timeout to 180 seconds. Searches and verifications run in real time against the target's mail servers and websites, so a single request can take that long.
• A request that runs longer than 180 seconds ends with 504 from the gateway. The body isn't JSON and has no errors object.
• The request body can be at most 4 MB. A larger body fails with 413 and {"error": "Request Entity Too Large"}.
• For lists of inputs, use bulk jobs instead of long-running loops of single requests.

Retries

Retry only the statuses that Errors marks as retryable:

Don't retry 400, 401, 402, 403, 404, 409, 413, 422, or 451: the same request fails the same way until you change it or your account. The exception is a 422 with type openai_error or search_failed from company search, which you can retry.

Use exponential backoff with a cap and random jitter, and stop after a fixed number of attempts. Failed requests aren't charged; see Credits and usage.

The API has no idempotency keys. Retrying a GET is safe, but retrying a request that creates something can create it twice. Before you retry one of these after a timeout or 5xx, list the resource to check whether the first attempt succeeded:

Repeated requests

Some repeats of a successful request are free. The duplicate-request rule defines which ones, and for how long. Read it before you add your own cache: a cache keyed on different parameters than the rule can cost credits the rule would have waived.

Request IDs

Responses from the API carry an X-Request-ID header. Log it with each request; quote it when you contact support about a failed request.

You can also set the ID yourself. Send an X-Request-ID header of printable ASCII characters and the API returns the same value. An empty value, or one with other characters, is replaced by a generated ID.

Code
curl -i "https://api.tomba.io/v1/email-verifier?email=jane.doe@stripe.com" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
  -H "X-Request-ID: order-sync-7f3c9a"

A 504 from the gateway doesn't carry the header. Sending your own ID gives you a value to quote in that case too.

Pagination

Paginated endpoints take a 1-based page. None accepts an offset. The page size and the names of the pagination fields differ between endpoints:

• On GET /v1/leads and GET /v1/bulk/{type}, total_pages is rounded down, so it can miss the last, partial page. Keep requesting pages until one returns fewer items than limit.
• On domain search and similar domains, a larger limit costs more credits; see Credit costs.
• On the Free plan, domain search and company search return only the first page; see Free plan limits.

Keys and secrets

• Keep the key and secret on your server, loaded from environment variables or a secrets manager. See Security.
• Use one key per integration, so you can rotate or delete one without touching the others.
• Every key expires. Track expires_at from GET /v1/keys, and alert on the X-Tomba-Key-Expired header and the api_key_expired error. See Key expiry.
• Rotate keys before they expire, following Rotate keys.

Webhooks

Callbacks sent to a webhook_url aren't signed. Put a hard-to-guess token in the URL, reject requests that don't carry it, and respond with a 2xx as soon as you've stored the payload. Webhooks describes the delivery and retry behavior.

Monitoring

• Subscribe to status.tomba.io for incidents and outages.
• Track your throttling headroom from the rate limit headers, or poll GET /v1/rate-limits, which isn't rate-limited itself.
• Track your credit balances with GET /v1/me, GET /v1/usage, or the quota headers on each response. See Check usage.
• Alert on rising 429, 5xx, and 504 rates, and on 402 quota_exceeded, which means a balance is too low for the request.