---
title: 狀態與錯誤碼
description: Nymwell 回傳的所有可註冊原因、工作流程狀態、訂單狀態與錯誤碼，以及 Agent 該如何處理。
---

# 狀態與錯誤碼

## 可否註冊

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

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

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

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

## 工作流程（workflow）

需要等人、等付款或等註冊商的操作，都會回傳 `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` | 意思 | 怎麼做 |
| --- | --- | --- |
| `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 | 重新報價 |
| `https_forwarding_required` | 402 | 用 HTTPS 提供網域頁面或轉址是付費加購（`price_display`，每網域每年）。把 `workflow.action.url` 交給使用者，由擁有者或管理員開啟；Agent 無法購買。 |
| `card_required`、`payment_failed` | 402 | 工作空間沒有存卡，或扣款被拒。沒有任何收費，請使用者到「帳務」更新卡片。 |
| `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），沒有任何收費 |