Overview

Error Handling

When an API call fails, the API returns one of the following status codes:

401: Invalid API key
429: Rate limit exceeded
400: Other error
404: Invalid request


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:

Error Code	Meaning
400	Bad Request – Your request is invalid.
401	Unauthorized – Your API key is wrong.
402	The Email Verification failed due to an unexpected response from the remote SMTP server. This failure is outside our control; we advise you to retry later.
403	Forbidden – The resource requested is hidden for administrators only.
404	Not Found – The specified resource could not be found.
405	Method Not Allowed – You tried to access a resource with an invalid method.
406	Not Acceptable – You requested a format that isn’t JSON.
410	Gone – The resource requested has been removed from our servers.
418	I’m a teapot.
429	Too Many Requests – You're requesting too many resources! Slow down!
500	Internal Server Error – We encountered a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please 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?.message);
}

Last modified on April 28, 2026

API Key and Authentication Usage Limits and Quotas

Error Codes

Tomba API uses the following error codes:

Error Code

Meaning

400

Bad Request – Your request is invalid.

401

Unauthorized – Your API key is wrong.

402

The Email Verification failed due to an unexpected response from the remote SMTP server. This failure is outside our control; we advise you to retry later.

403

Forbidden – The resource requested is hidden for administrators only.

404

Not Found – The specified resource could not be found.

405

Method Not Allowed – You tried to access a resource with an invalid method.

406

Not Acceptable – You requested a format that isn’t JSON.

410

Gone – The resource requested has been removed from our servers.

418

I’m a teapot.

429

Too Many Requests – You're requesting too many resources! Slow down!

500

Internal Server Error – We encountered a problem with our server. Try again later.

503

Service Unavailable – We’re temporarily offline for maintenance. Please 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?.message);
}

Last modified on April 28, 2026