---
title: Statuses and errors
description: Every availability reason, workflow state, order status and error code Nymwell returns, and what an agent should do with each.
---

# 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`:

```json
{
  "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 |
| `https_forwarding_required` | 402 | Serving the domain page or a redirect over HTTPS is a paid add-on (`price_display`, per domain per year). Give the person `workflow.action.url`; an owner or admin turns it on. Agents can't buy it. |
| `card_required`, `payment_failed` | 402 | The workspace has no saved card, or it was declined. Nothing was charged; the person updates the card in Billing. |
| `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 |