Error Handling

All errors share a single JSON shape:

{"error": "error_code"}

Some responses add additional fields (e.g. message) but error is always present.

HTTP status code conventions

Status	Meaning	Typical `error` codes
`400`	Bad request — malformed JSON, missing required field, invalid value	`invalid_request`, `invalid_address`, `invalid_domain`
`401`	Missing or invalid authentication	`unauthorized`
`403`	Authenticated but not allowed (ownership, plan, or status)	`forbidden`, `inactive_status`, `not_owner`
`404`	Resource not found	`not_found`
`409`	Conflict (duplicate address, duplicate domain, etc.)	`address_taken`, `domain_exists`
`422`	Semantically invalid	`weak_password`
`429`	Rate-limited or quota-exhausted	`rate_limit_exceeded`, `quota_exceeded`
`500`	Internal error	`internal_error`

unauthorized — missing, expired, or invalid Bearer token.
forbidden — token valid but you don't own the resource.
not_found — resource doesn't exist or has been deleted.
rate_limit_exceeded — too many requests in the current window. Retry after a short backoff.
quota_exceeded — Pro monthly ops quota exhausted. Upgrade plan or wait until next cycle.
address_taken — the requested address is already registered.
inactive_status — Pro account is suspended or cancelled; contact support or resume subscription.

429 rate_limit_exceeded — safe to retry after a short backoff (200–500 ms).
429 quota_exceeded — do not retry; wait until quota resets (first of month) or upgrade.
5xx — retry with exponential backoff up to a reasonable ceiling.
4xx (other than 429) — do not retry; fix the request.