レート制限とべき等性

べき等性

POST に Idempotency-Key ヘッダーを付けて送信すると、安全にリトライできるようになります。オペレーションごとに、新しい一意の値（UUID、または onboarding-8841 のような自社システムの ID）を使用してください。値は 1〜255 文字の印字可能な ASCII 文字です。

curl https://api.bonafidesign.com/v1/envelopes \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2f0e-1d0b-4c2a-9a59-3f1f1c7d2b11" \
  -d @envelope.json

キーを付けた最初のリクエストは通常どおり実行され、そのレスポンスが 24 時間保存されます。
同じキーと同じリクエスト（メソッド、パス、クエリ、本文）でリトライすると、保存されたレスポンスが Idempotent-Replayed: true ヘッダー付きで再送されます。
同じキーで異なるリクエストを送ると 422 idempotency-key-reused になります。
最初のリクエストがまだ実行中にリトライすると 409 idempotency-in-progress になります。少し待ってからリトライしてください。
5xx レスポンスは保存されないため、サーバーエラーの後のリトライは再度実行されます。

キーのスコープは呼び出し元、つまりキーを送信した組織と API キー（またはダッシュボードユーザー）です。キーを受け付けるオペレーションには、 API リファレンスで Idempotency-Key ヘッダーパラメーターが示されています。テンプレートの作成、ファイルのアップロード、公開、エンベロープの作成と無効化、リンクの再送、署名セッションの発行、署名リンクと Webhook エンドポイントの作成、イベントの再配信などが該当します。

独自の ID による重複排除

べき等キーは 1 つのリクエストのリトライを保護します。ビジネス上のオブジェクトが一度しか送信されないようにするには、独自の ID と dedupeOn も送信してください。

{ "template": "tpl_…", "externalId": "user_8841", "dedupeOn": "external_id", "…": "…" }

その externalId を持つエンベロープが（同じモードで）すでに存在する場合、POST /v1/envelopes は新しく作成せずに、既存のエンベロープを 200 と x-deduplicated: true 付きで返します。これはキー、日付、同時リクエストをまたいで適用されます。

レート制限

認証済みの API（API キー）には、現在、固定のリクエストレート制限はありません。送信量はプランによって制限されます。制限は、不正利用のおそれがある箇所に適用されます。

対象	制限
`POST /v1/public/verify`	IP ごとに 1 分あたり 60 リクエスト
`GET /v1/public/anchors…`、`/.well-known/bona-fide/*`	IP ごとに 1 分あたり 240 リクエスト
`GET /v1/sso/discover`	IP ごとに 1 分あたり 30 回の照会
署名者のワンタイムコード	セッションごとに 15 分あたり 5 コード、コードごとに 5 回の試行
受信者への再送	受信者ごとに 1 分に 1 回
常設リンク	リンクごと：`perEmailPerDay`（デフォルト 3）、`perIpPerHour`（デフォルト 20）、任意の `dailyCap`
ダッシュボードへのパスワードによるログイン	IP ごとに 1 分あたり 10 回、メールアドレスごとに 15 分あたり 10 回
パスワードによるダッシュボードへの新規登録	IP ごとに 1 分あたり 5 回、メールアドレスごとに 1 時間あたり 5 回
パスワードリセットのメール	IP ごとに 15 分あたり 5 回、メールアドレスごとに 1 時間あたり 3 回
ダッシュボードのログインコード	IP ごとに 1 分あたり 3 回

制限のある公開エンドポイントは、RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset（秒）ヘッダーを送信します。上限を超えると、API は rate-limited problem とともに 429 を返し、通常は秒数を示す Retry-After ヘッダーが付きます。