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
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 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

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

/tlds Endpoint

Error	Description
invalid_type	The type filter must be gTLD or ccTLD

/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

Error Handling Example

Python

import requests

response = requests.get(
    "https://api.domainkit.bot/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.domainkit.bot/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:

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

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