Error Codes

All API errors return a consistent JSON format with an error code and message.

Error Response Format

{
  "error": "error_code",
  "message": "Human-readable description"
}

Error Codes

400 Bad Request

Error	Message	Solution
`missing_parameter`	Required parameter is missing	Provide the required parameter (e.g., `name` for /check)
`invalid_name`	Name must be 1-63 characters, alphanumeric with hyphens	Use valid domain name characters
`unsupported_tld`	TLD not supported	Check `/tlds` for supported TLDs
`invalid_category`	Unknown category	Use `GET /tlds` to list available categories
`too_many_tlds`	Maximum 20 TLDs per request	Reduce the number of TLDs in your comma-separated list or use a smaller category
`missing_domain`	Domain parameter is required	Provide the `domain` parameter for /register
`invalid_domain`	Domain must include TLD	Include TLD (e.g., `example.com` not `example`)
`invalid_registrar`	Unknown registrar	Use: `porkbun`, `namecheap`, or `godaddy`
`invalid_type`	Type must be ‘gTLD’ or ‘ccTLD’	Use valid type filter for /tlds

404 Not Found

Error	Message	Solution
`not_found`	Endpoint or resource not found	Check the URL and HTTP method

429 Too Many Requests

Error	Message	Solution
`rate_limit_exceeded`	Too many requests	Wait and retry using the `Retry-After` header

Response includes Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 60 seconds."
}

500 Internal Server Error

Error	Message	Solution
`internal_error`	An unexpected error occurred	Retry the request; contact support if persistent
`check_failed`	Availability check failed	Retry; may indicate an upstream RPC error (ENS)
`metadata_failed`	Metadata lookup failed	Retry; may indicate an upstream RPC error (ENS)

503 Service Unavailable

Error	Message	Solution
`service_unavailable`	Service temporarily unavailable	Check status page; retry later

Per-Endpoint Errors

/check Endpoint

Error	Description
`missing_parameter`	The `name` parameter was not provided
`invalid_name`	Name contains invalid characters or is too long
`unsupported_tld`	The specified TLD is not in the supported list
`invalid_category`	Unknown category name. Use `GET /tlds` for categories.
`too_many_tlds`	More than 20 TLDs specified (via comma-separated list or category)

/tlds Endpoint

Error	Description
`invalid_type`	The `type` filter must be `gTLD` or `ccTLD`
`invalid_category`	Unknown category name

/register Endpoint

Error	Description
`missing_domain`	The `domain` parameter was not provided
`invalid_domain`	Domain is missing a TLD (e.g., passed `example` instead of `example.com`)
`invalid_registrar`	The `registrar` filter is not a supported registrar

ENS /check Endpoint

Error	Description
`missing_parameter`	The `name` parameter was not provided
`invalid_name`	ENS name must be 3-63 chars, lowercase alphanumeric with hyphens
`check_failed`	Ethereum RPC error while checking availability

ENS /metadata Endpoint

Error	Description
`missing_parameter`	The `name` parameter was not provided
`invalid_name`	Invalid ENS name format
`not_found`	ENS name is not registered
`metadata_failed`	Ethereum RPC error while fetching metadata

Error Handling Example

Python

import requests

response = requests.get(
    "https://api.robotdomainsearch.com/check",
    params={"name": "example"}
)

if response.status_code == 200:
    data = response.json()
    # Process results
elif response.status_code == 400:
    error = response.json()
    print(f"Bad request: {error['message']}")
elif response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 60))
    print(f"Rate limited. Retry after {retry_after} seconds.")
else:
    print(f"Error {response.status_code}: {response.text}")

JavaScript

try {
  const response = await fetch(
    "https://api.robotdomainsearch.com/check?name=example"
  );
  
  if (!response.ok) {
    const error = await response.json();
    
    if (response.status === 429) {
      const retryAfter = response.headers.get("Retry-After") || 60;
      console.log(`Rate limited. Retry after ${retryAfter}s`);
    } else {
      console.log(`Error: ${error.message}`);
    }
    return;
  }
  
  const data = await response.json();
  // Process results
} catch (err) {
  console.log("Network error:", err);
}

Getting Help

If you encounter persistent errors:

Check the status page for outages
Review the API documentation for correct usage
Open an issue on GitHub

📄 Raw markdown: /docs/api/errors.md