Statuses and errors

Availability

Each name from search or suggestions has available.

Field	Values
`tier` (when available)	`standard`: the ending's usual price. `premium`: priced higher by the registry; tell the person.
`reason` (when not available)	See below

`reason`	Means	Do
`domain_unavailable`	Someone has it, or the registry holds it	Suggest other names
`extension_not_supported`	Nymwell can't sell this ending	Try another ending
`extension_disallows_registration`	The registry is not taking new names in this ending	Try another ending

Availability comes only from the registrar. DNS, WHOIS, RDAP and screen_domains are screening.

Workflow

Anything that waits on a person, a payment or the registrar returns workflow:

{
  "state": "action_required",
  "completed": false,
  "action": {"type": "pay_checkout", "url": "https://checkout.stripe.com/…", "message": "Give url to the person; paying is their approval."},
  "links": {"self": "https://nymwell.com/api/v1/orders?id=ord_…"}
}

`state`	Means	Do
`in_progress`	Nymwell or the registrar is working on it	Check `links.self` again in a few seconds
`blocked`	Waiting on a third party, such as the current registrar releasing a transfer	Check again later; tell the person it can take days
`action_required`	Waiting on the person (`action.type`: `pay_checkout` or `approve_in_console`)	Give the person `action.url`; stop polling until they act
`succeeded`	Done (`completed: true`)	Stop
`failed`	Ended without doing it (`completed: true`); `error.code` and `error.message` say why	Tell the person; don't retry without them

Order statuses

status on an order, and the workflow state it maps to.

`status`	`workflow.state`
`awaiting_payment`	`action_required` (pay_checkout)
`registering`, `renewing`, `transferring`	`in_progress`
`needs_attention`	`in_progress`: the registrar didn't answer clearly; Nymwell checks before retrying, so nothing is bought twice
`transfer_pending`	`blocked`: the current registrar usually releases within 5 days
`registered`, `renewed`, `transferred`	`succeeded`
`checkout_expired`	`failed`: the person didn't pay; quote again
`failed_refunded`	`failed`: the registrar refused and the payment was refunded
`payment_failed`	`failed`: auto-renew couldn't charge the saved card
`failed`	`failed`

Approvals (list_approvals, GET /api/v1/approvals): pending is action_required (approve_in_console); approved and applied is succeeded; rejected, expired and cancelled are failed.

Error codes

`error`	HTTP	Do
`authentication_required`	401	The call needs the person's account: give them `buy_url`, or connect to `https://nymwell.com/mcp/account`
`invalid_token`, `invalid_api_key`	401	Sign in again, or ask for a new key
`insufficient_scope`	403	The key lacks that scope
`domain_access_denied`	403	The key's domain allowlist excludes this domain
`invalid_domain`	400	Send a name like `example.com`, without a path or email
`rate_limited`	429	Wait `retry_after_seconds`
`domain_unavailable`	409	Someone has it; search again
`term_not_available`	422	That number of years isn't offered; `get_tld_info` lists the allowed terms
`quote_expired`, `quote_not_active`	409	Get a new quote
`registrant_required`	409	A signed-in owner adds who domains are registered to, at https://nymwell.com/app/billing/#registrant
`registrar_funds_low`	503	Buying is paused; nothing was charged
`integration_not_configured`	503	That part isn't connected yet; `GET /api/v1/status` shows what is
`registrar_error`	422 or 502	The registrar refused (422) or didn't answer (502); nothing was charged