速率限制與冪等性

冪等性

在 POST 要求上傳送 Idempotency-Key 標頭，即可安全地重試該要求。請為每項作業使用全新且唯一的值（UUID，或您自己系統中的 ID，例如 onboarding-8841）：長度為 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 去重複

冪等金鑰保護的是同一個要求的重試。若要確保某個業務物件只會傳送一次，也請一併傳送您自己的 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 每分鐘 60 個要求
`GET /v1/public/anchors…`、`/.well-known/bona-fide/*`	每個 IP 每分鐘 240 個要求
`GET /v1/sso/discover`	每個 IP 每分鐘 30 次查詢
簽署人一次性驗證碼	每個工作階段每 15 分鐘 5 組驗證碼；每組驗證碼可嘗試 5 次
重新寄送給收件者	每位收件者每分鐘一次
常設連結	依連結：`perEmailPerDay`（預設 3）、`perIpPerHour`（預設 20）、選用的 `dailyCap`
主控台密碼登入	每個 IP 每分鐘 10 次；每個電子郵件地址每 15 分鐘 10 次
主控台以密碼註冊	每個 IP 每分鐘 5 次；每個電子郵件地址每小時 5 次
密碼重設郵件	每個 IP 每 15 分鐘 5 次；每個電子郵件地址每小時 3 次
主控台登入驗證碼	每個 IP 每分鐘 3 次

受限的公開端點會傳送 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset（秒）標頭。超出限制時，API 會傳回 429 和一個 rate-limited 問題，通常也會附上以秒為單位的 Retry-After 標頭。