Error Codes

All API errors return a consistent JSON format:

{
  "error": "Human-readable error title",
  "message": "Detailed description of what went wrong",
  "code": "ERROR_CODE"
}

Error code reference

Client errors (4xx)

Code	HTTP Status	Description	Action
VALIDATION_ERROR	400	Request body or params failed validation	Check request format against the API reference
TLD_NOT_SUPPORTED	400	TLD is not in our supported list	Use GET /domains/pricing to see supported TLDs
DOMAIN_TOO_EXPENSIVE	400	Domain price exceeds internal safety limit	Contact support or try a different domain
AUTH_REQUIRED	401	Missing or invalid Authorization header	Authenticate with SIWE first
TOKEN_EXPIRED	401	JWT access token has expired	Refresh your token
TOKEN_INVALID	401	JWT is malformed or signature is invalid	Re-authenticate with SIWE
PAYMENT_REQUIRED	402	Endpoint requires x402 payment	See x402 Payment Flow
PAYMENT_INVALID	402	Payment signature is malformed or invalid	Check your x402 payment implementation
PAYMENT_INSUFFICIENT	402	Wallet doesn’t have enough USDC	Fund your wallet on Base with USDC
OWNERSHIP_DENIED	403	You don’t own this domain	DNS operations require the registering wallet
NOT_FOUND	404	Domain, record, or resource not found	Verify the domain name or record ID
DOMAIN_UNAVAILABLE	409	Domain is already registered	Search for alternative domains
RATE_LIMITED	429	Too many requests	Wait and retry. See Rate Limits

Server errors (5xx)

Code	HTTP Status	Description	Action
REGISTRATION_FAILED	500	Domain registration failed at the registry	Retry or contact support
DNS_ERROR	500	DNS operation failed at the registry	Retry or contact support
SERVICE_UNAVAILABLE	503	Dependent service is down (DB, Redis, registrar)	Check GET /health and retry later

Rate limit headers

When rate limited, the response includes:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708531200

{
  "error": "Too many requests",
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "code": "RATE_LIMITED"
}