錯誤

錯誤使用 HTTP 狀態碼，回應本文採用 RFC 9457 格式，並帶有 Content-Type: application/problem+json：

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/recipients/0/email", "message": "Invalid email address" },
    { "pointer": "/recipients", "message": "Missing recipient for role 'company'." },
    { "pointer": "/recipients/1/role", "message": "Unknown role 'cfo'.", "hint": "Template roles: client, company" }
  ],
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

成員	意義
`type`	穩定的識別碼：`https://bonafidesign.com/problems/<slug>`。請依據它（或其 slug）決定處理分支，而不要依據 `title` 或 `detail`
`title`	該類型的簡短摘要
`status`	HTTP 狀態碼
`detail`	針對這次錯誤的說明文字
`errors`	驗證問題：`pointer`（指向要求本文、查詢參數或變數的 JSON Pointer）、`message`，以及選用的 `hint`
`requestId`	也包含在 `x-request-id` 標頭中。聯絡支援團隊時請提供
`upgradeUrl`	出現在方案限制（`402`、`403 plan-upgrade-required`）中：新增信用卡或升級方案的位址

一個要求的所有驗證問題會一次全部回報，因此用戶端可以把每個問題都顯示在對應的欄位旁邊。

錯誤類型

狀態碼	Slug	觸發時機
400	`bad-request`	要求格式錯誤，例如本文不是有效的 JSON
401	`unauthorized`	憑證遺失、格式錯誤、已撤銷或已到期
402	`payment-required`	Free 工作區在本期已用完內含的已完成信封額度；請新增信用卡或升級方案（測試模式不受影響）
403	`forbidden`	已通過驗證但不允許操作：缺少權限、在僅限主控台的端點上使用 API 金鑰、跨網站要求
403	`plan-upgrade-required`	工作區的方案不包含此功能
403	`verification-required`	簽署人在驗證一次性驗證碼之前就提交了
404	`not-found`	該資源不存在於您的組織中，或路由不存在
409	`invalid-state`	此操作不符合目前的狀態，例如作廢已完成的信封，或為已簽署的收件者核發工作階段
409	`not-your-turn`	簽署人在先前的傳送群組完成之前就提交了
409	`document-mismatch`	文件在向簽署人顯示之後已有變更（`viewedDocumentHash`）
409	`already-signed`	此電子郵件地址已簽署過這個常設連結
409	`in-use`	刪除正被信封或簽署連結使用的範本
409	`no-draft`	發布沒有草稿的範本
409	`idempotency-in-progress`	使用相同 `Idempotency-Key` 的要求仍在處理中
409	`conflict`	其他衝突
410	`gone`	簽署工作階段已使用過或已到期
413	`payload-too-large`	上傳的內容超過限制（範本檔案為 25 MB）
415	`unsupported-media-type`	上傳了不支援的類型
422	`validation-error`	本文、查詢參數或變數無效；請參閱 `errors`
422	`idempotency-key-reused`	相同的 `Idempotency-Key` 用於不同的要求
422	`conversion-failed`	無法轉換 Word 文件
429	`rate-limited`	要求過多；若有 `Retry-After`，請等待其指定的秒數
500	`internal`	未預期的錯誤。可使用相同的 `Idempotency-Key` 安全地重試
501	`not-implemented`	此功能已定義於結構描述中，但尚未實作（例如簡訊驗證碼）
503	`converter-unavailable`、`billing-unavailable`	某項相依服務暫時無法使用；請稍後再試

處理錯誤

const res = await fetch('https://api.bonafidesign.com/v1/envelopes', { method: 'POST', headers, body });
if (!res.ok) {
  const problem = await res.json(); // application/problem+json
  const slug = problem.type.split('/').pop();
  if (slug === 'validation-error') {
    for (const e of problem.errors) form.setError(e.pointer, e.message);
  } else if (slug === 'payment-required') {
    showUpgrade(problem.upgradeUrl);
  } else {
    throw new Error(`${problem.title} (${problem.requestId})`);
  }
}