エラー

エラーは HTTP ステータスコードと、Content-Type: application/problem+json の RFC 9457 形式の本文で返されます。

{
  "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>`。分岐にはこの値（またはスラッグ）を使い、`title` や `detail` は使わないでください
`title`	type の短い概要
`status`	HTTP ステータス
`detail`	今回発生したエラーについての、人が読める説明
`errors`	検証の問題：`pointer`（リクエスト本文、またはクエリや変数の中を指す JSON Pointer）、`message`、任意の `hint`
`requestId`	`x-request-id` ヘッダーにも含まれます。サポートへの問い合わせ時にお伝えください
`upgradeUrl`	プランによる制限（`402`、`403 plan-upgrade-required`）の場合：カードを追加またはアップグレードする場所

リクエストの検証の問題はすべて一度に報告されるため、クライアントはそれぞれを該当するフィールドの横に表示できます。

エラーの種類

ステータス	スラッグ	発生する状況
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`	スキーマには存在するが、まだ実装されていない機能（例：SMS のコード）
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})`);
  }
}