速率限制与幂等性

幂等性

在 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 响应头。