Platform

Errors

When a request fails, the response body contains an errors object. Branch on errors.type: one HTTP status can cover several causes.

Error format


Code
{
    "errors": {
        "type": "params_invalid",
        "message": "Either domain or company parameter must be provided.",
        "code": 422
    }
}

Field	Description
`type`	Machine-readable cause. The values are listed under Error types.
`message`	Human-readable explanation. The wording can change; don't match on it.
`code`	The HTTP status code of the response.

errors is always a single object, never an array. Responses from the API carry an X-Request-ID header, and you can send your own (Request IDs); include it when you contact support about a failed request.

A few failures don't use this format:

A request body larger than 4 MB returns 413 with {"error": "Request Entity Too Large"}.
A request that runs longer than 180 seconds returns 504 from the gateway, with a non-JSON body.
GET /people/find, GET /companies/find, and GET /combined/find return status 200 with an errors body, code 404 or 422, when nothing is found or the input is a disposable or webmail address. Check the body for errors on these endpoints.

Status codes

Status	Meaning	Retry?
`200`	Success	—
`201`	Resource created. `GET /email-sources` also returns `201`, with no data, when it finds no sources.	—
`400`	Credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request	No. Fix the request.
`401`	Credentials don't match an account, the account can't use the API, or the OAuth token is invalid	No
`402`	Not enough credits for the request	No. Wait for your usage window to renew or add credits.
`403`	The OAuth token lacks a scope, or the plan doesn't include the feature	No
`404`	The route or record doesn't exist	No
`408`	The email verifier couldn't complete the mailbox check	Yes, later
`409`	A duplicate record, or a bulk job whose status doesn't allow the action	No
`413`	The request body is larger than 4 MB	No
`422`	A parameter failed validation, or an account cap was reached	No. Fix the request.
`429`	A rate limit was hit, or the email count or sources balance is used up	Yes, after `Retry-After`, for rate limits
`451`	The address, profile, or phone number is withheld at its owner's request	No
`500`	Server error	Yes, with backoff
`504`	The request took longer than 180 seconds	Yes, or use bulk jobs

None of the error responses consume credits.

Error types

`errors.type`	Status	Cause	What to do
`params_invalid`	422, 400	A parameter failed validation (422), or a plan rule rejected it (400), such as the Free plan's result limit.	Correct the parameter named in the message.
`unknown_record`	404, 400	The record doesn't exist (404), or the email finder received a disposable or webmail domain (400).	Check the ID or the input.
`unknown_route`	404	The URL doesn't match an endpoint.	Check the method and path in the API reference.
`not_found`	404	The requested log entry doesn't exist. The find endpoints also return it inside a `200` response.	—
`authentication_failed`	400, 401, 403	The credentials are missing, malformed, or wrong, or the account can't use the API.	See Authentication.
`api_key_expired`	400	The API key is past its expiry date. The `X-Tomba-Key-Expired` header gives the date.	Rotate the key.
`invalid_token`	401	The OAuth access token is invalid, expired, or revoked.	Refresh the token or re-authorize.
`insufficient_scope`	403	The OAuth access token lacks the scope the endpoint needs.	Request the scope; see OAuth 2.0.
`forbidden`	403	A workspace member without admin rights requested team or member usage.	Use `scope=user`, or ask a workspace admin.
`quota_exceeded`	402	The search or verification balance, or the member's individual limit, is lower than the request's cost.	See Credits and usage.
`rate_limit`	429, 422	429: a rate limit was hit, or the email count or sources balance is used up. 422: the account reached its cap on API keys, leads, lead lists, or lead attributes.	For 429, see Handle 429 responses. For 422, remove items or change plan.
`proxy_error`	408	The email verifier's mailbox check failed.	Retry later.
`duplicate_record`	409	A flag for the same item is already pending review.	Wait for the review.
`invalid_state`	409	The bulk job's status doesn't allow the action, such as launching a job that is already running, or the job has expired. The message says which.	Check the job's `status`; see Lifecycle.
`claimed_email`, `claimed_linkedin`, `claimed_phone`	451	The person asked Tomba to stop processing their data, so the address, LinkedIn profile, or phone number is withheld permanently.	Remove the record from your data.
`ip_blocked`	400	Tomba's firewall blocks the request's IP address.	Contact support.
`openai_error`, `search_failed`	422	Company search couldn't process the query.	Retry, or simplify the query.
`internal_error`	500	A live technology lookup failed.	Retry with backoff.
`api_error`	500, 400, 404, 422	An unexpected error, or a bulk job without the requested result file (404).	Retry a 500 with backoff. If it persists, contact support with the `X-Request-ID`.

Handle errors

Last modified on October 1, 2026

Rate limits Webhooks

Error format

Code

{
    "errors": {
        "type": "params_invalid",
        "message": "Either domain or company parameter must be provided.",
        "code": 422
    }
}

Field	Description
`type`	Machine-readable cause. The values are listed under Error types.
`message`	Human-readable explanation. The wording can change; don't match on it.
`code`	The HTTP status code of the response.

A few failures don't use this format:

A request body larger than 4 MB returns 413 with {"error": "Request Entity Too Large"}.

A request that runs longer than 180 seconds returns 504 from the gateway, with a non-JSON body.

GET /people/find, GET /companies/find, and GET /combined/find return status 200 with an errors body, code 404 or 422, when nothing is found or the input is a disposable or webmail address. Check the body for errors on these endpoints.

Status codes

Status	Meaning	Retry?
`200`	Success	—
`201`	Resource created. `GET /email-sources` also returns `201`, with no data, when it finds no sources.	—
`400`	Credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request	No. Fix the request.
`401`	Credentials don't match an account, the account can't use the API, or the OAuth token is invalid	No
`402`	Not enough credits for the request	No. Wait for your usage window to renew or add credits.
`403`	The OAuth token lacks a scope, or the plan doesn't include the feature	No
`404`	The route or record doesn't exist	No
`408`	The email verifier couldn't complete the mailbox check	Yes, later
`409`	A duplicate record, or a bulk job whose status doesn't allow the action	No
`413`	The request body is larger than 4 MB	No
`422`	A parameter failed validation, or an account cap was reached	No. Fix the request.
`429`	A rate limit was hit, or the email count or sources balance is used up	Yes, after `Retry-After`, for rate limits
`451`	The address, profile, or phone number is withheld at its owner's request	No
`500`	Server error	Yes, with backoff
`504`	The request took longer than 180 seconds	Yes, or use bulk jobs

None of the error responses consume credits.

Error types

`errors.type`	Status	Cause	What to do
`params_invalid`	422, 400	A parameter failed validation (422), or a plan rule rejected it (400), such as the Free plan's result limit.	Correct the parameter named in the message.
`unknown_record`	404, 400	The record doesn't exist (404), or the email finder received a disposable or webmail domain (400).	Check the ID or the input.
`unknown_route`	404	The URL doesn't match an endpoint.	Check the method and path in the API reference.
`not_found`	404	The requested log entry doesn't exist. The find endpoints also return it inside a `200` response.	—
`authentication_failed`	400, 401, 403	The credentials are missing, malformed, or wrong, or the account can't use the API.	See Authentication.
`api_key_expired`	400	The API key is past its expiry date. The `X-Tomba-Key-Expired` header gives the date.	Rotate the key.
`invalid_token`	401	The OAuth access token is invalid, expired, or revoked.	Refresh the token or re-authorize.
`insufficient_scope`	403	The OAuth access token lacks the scope the endpoint needs.	Request the scope; see OAuth 2.0.
`forbidden`	403	A workspace member without admin rights requested team or member usage.	Use `scope=user`, or ask a workspace admin.
`quota_exceeded`	402	The search or verification balance, or the member's individual limit, is lower than the request's cost.	See Credits and usage.
`rate_limit`	429, 422	429: a rate limit was hit, or the email count or sources balance is used up. 422: the account reached its cap on API keys, leads, lead lists, or lead attributes.	For 429, see Handle 429 responses. For 422, remove items or change plan.
`proxy_error`	408	The email verifier's mailbox check failed.	Retry later.
`duplicate_record`	409	A flag for the same item is already pending review.	Wait for the review.
`invalid_state`	409	The bulk job's status doesn't allow the action, such as launching a job that is already running, or the job has expired. The message says which.	Check the job's `status`; see Lifecycle.
`claimed_email`, `claimed_linkedin`, `claimed_phone`	451	The person asked Tomba to stop processing their data, so the address, LinkedIn profile, or phone number is withheld permanently.	Remove the record from your data.
`ip_blocked`	400	Tomba's firewall blocks the request's IP address.	Contact support.
`openai_error`, `search_failed`	422	Company search couldn't process the query.	Retry, or simplify the query.
`internal_error`	500	A live technology lookup failed.	Retry with backoff.
`api_error`	500, 400, 404, 422	An unexpected error, or a bulk job without the requested result file (404).	Retry a 500 with backoff. If it persists, contact support with the `X-Request-ID`.

Handle errors

const res = await fetch(
    "https://api.tomba.io/v1/email-finder?domain=stripe.com&full_name=Jane%20Doe",
    {
        headers: {
            "X-Tomba-Key": process.env.TOMBA_API_KEY,
            "X-Tomba-Secret": process.env.TOMBA_SECRET_KEY,
        },
    },
);
const body = await res.json();

if (body.errors) {
    const { type, message } = body.errors;
    const requestId = res.headers.get("X-Request-ID");
    if (type === "rate_limit" && res.status === 429) {
        // Wait for Retry-After, then retry. See /rate-limits.
    } else if (res.status === 408 || res.status >= 500) {
        // Transient: retry later with backoff.
    } else {
        throw new Error(
            `${res.status} ${type}: ${message} (request ${requestId})`,
        );
    }
} else {
    console.log(body.data);
}

Last modified on October 1, 2026