狀態與錯誤碼

可否註冊

查詢與建議的每個網域都有 available。

欄位	值
`tier`（可註冊時）	`standard`：該結尾的一般價格。`premium`：註冊局定的較高價格，請告訴使用者。
`reason`（無法註冊時）	見下表

`reason`	意思	怎麼做
`domain_unavailable`	已被註冊，或被註冊局保留	建議其他名稱
`extension_not_supported`	Nymwell 不賣這個結尾	換一個結尾
`extension_disallows_registration`	註冊局暫停受理這個結尾的新註冊	換一個結尾

可否註冊只以註冊商的回覆為準；DNS、WHOIS、RDAP 與 screen_domains 只是初篩。

工作流程（workflow）

需要等人、等付款或等註冊商的操作，都會回傳 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`	意思	怎麼做
`in_progress`	Nymwell 或註冊商處理中	幾秒後再查 `links.self`
`blocked`	在等第三方，例如原註冊商放行轉出	稍後再查，告訴使用者可能要幾天
`action_required`	在等使用者（`action.type`：`pay_checkout` 付款或 `approve_in_console` 核准）	把 `action.url` 交給使用者，等他完成前不要一直查
`succeeded`	完成（`completed: true`）	停止
`failed`	沒有完成就結束（`completed: true`），原因在 `error.code` 與 `error.message`	告訴使用者，沒有他同意不要重試

訂單狀態

訂單的 status 與對應的 workflow 狀態：

`status`	`workflow.state`
`awaiting_payment`	`action_required`（pay_checkout）
`registering`、`renewing`、`transferring`	`in_progress`
`needs_attention`	`in_progress`：註冊商回覆不明確，Nymwell 會先確認再重試，不會重複購買
`transfer_pending`	`blocked`：原註冊商通常 5 天內放行
`registered`、`renewed`、`transferred`	`succeeded`
`checkout_expired`	`failed`：使用者沒有付款，請重新報價
`failed_refunded`	`failed`：註冊商拒絕，款項已退回
`payment_failed`	`failed`：自動續約無法向保存的卡片扣款
`failed`	`failed`

核准（list_approvals、GET /api/v1/approvals）：pending 為 action_required（approve_in_console）；已核准且套用完成為 succeeded；rejected、expired、cancelled 為 failed。

錯誤碼

`error`	HTTP	怎麼做
`authentication_required`	401	需要使用者帳戶：給他 `buy_url`，或改連 `https://nymwell.com/mcp/account`
`invalid_token`、`invalid_api_key`	401	重新登入，或請使用者建立新的 key
`insufficient_scope`	403	key 缺少這個權限
`domain_access_denied`	403	key 的網域允許清單不含這個網域
`invalid_domain`	400	請送 `example.com` 這樣的名稱，不含路徑或 Email
`rate_limited`	429	等 `retry_after_seconds` 秒
`domain_unavailable`	409	已被註冊，請換名稱
`term_not_available`	422	不提供這個年數，`get_tld_info` 會列出可選年限
`quote_expired`、`quote_not_active`	409	重新報價
`registrant_required`	409	已登入的擁有者到 https://nymwell.com/app/billing/#registrant 填寫網域登記人
`registrar_funds_low`	503	暫停購買，沒有任何收費
`integration_not_configured`	503	該功能尚未接上，`GET /api/v1/status` 會顯示目前狀態
`registrar_error`	422 或 502	註冊商拒絕（422）或沒有回應（502），沒有任何收費