Copy page

Overview

Error Handling

When an API call fails, the response body is always the same envelope: a single errors object carrying a machine-readable type, a human-readable message, and the HTTP status as code. errors is never an array.

Branch on errors.type rather than on the status code alone — one status can cover several distinct causes.

Code
{
    "errors": {
        "type": "unknown_route",
        "message": "Invalid request, please make sure you follow the documentation for proper syntax",
        "code": 404
    }
}

Error Codes

Tomba API uses the following error codes:

Status	errors.type	Meaning
400	params_invalid	A parameter was rejected by a plan or business rule — for example, the Free plan result cap.
400	unknown_record	The input was recognised but unusable, such as a disposable email domain.
400	ip_blocked	The request IP is blocked by our firewall. Contact us if you believe this is a mistake.
401	authentication_failed	Your API key or secret is missing, malformed, or does not match an account.
401	api_key_expired	The key has passed its expiry date. The X-Tomba-Key-Expired response header carries the timestamp. Create a new key at app.tomba.io/api.
401	invalid_token	OAuth 2.0 Bearer token or session is missing, expired, or revoked.
402	quota_exceeded	Not enough search or verification credits remain for this request. Check your balance with GET /me.
404	unknown_route	The URL does not match any endpoint.
404	unknown_record	The endpoint is valid but the resource does not exist.
409	duplicate_record	The resource already exists.
422	params_invalid	A required parameter is missing or failed validation. Only the first failing field is reported, inside message.
429	rate_limit	A per-second, per-minute or daily limit was hit, or your account credits are exhausted. Check Retry-After and x-daily-reset-seconds. See Rate Limits.
451	claimed_email	The person owning this address has asked us to stop processing their personal data. The address is permanently withheld, and the request does not consume credits.
500	api_error	Something went wrong on our side. Retry with backoff; if it persists, send us the X-Request-Id response header.
503	—	Temporarily offline for maintenance. Try again later.

Example: Inspect Error Responses

Use -i to inspect both status code and headers:

Code
curl -i -X GET "https://api.tomba.io/v1/domain-search?domain=" \
  -H "X-Tomba-Key: your_api_key" \
  -H "X-Tomba-Secret: your_secret_key"

Handle API errors in JavaScript:

Code
const res = await fetch("https://api.tomba.io/v1/domain-search?domain=", {
    headers: {
        "X-Tomba-Key": "your_api_key",
        "X-Tomba-Secret": "your_secret_key",
    },
});

if (!res.ok) {
    const err = await res.json();
    console.error(res.status, err.errors?.type, err.errors?.message);
}