Giới hạn tần suất và tính lũy đẳng

Tính lũy đẳng

Gửi header Idempotency-Key cùng một yêu cầu POST để có thể thử lại yêu cầu đó một cách an toàn. Dùng một giá trị mới, duy nhất cho mỗi thao tác (một UUID, hoặc một id từ hệ thống của bạn như onboarding-8841): từ 1 đến 255 ký tự ASCII in được.

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

Yêu cầu đầu tiên với một khóa chạy bình thường và phản hồi của nó được lưu trong 24 giờ.
Một lần thử lại với cùng khóa và cùng yêu cầu (phương thức, đường dẫn, query và nội dung) sẽ nhận lại phản hồi đã lưu, kèm header Idempotent-Replayed: true.
Cùng khóa nhưng yêu cầu khác sẽ trả về 422 idempotency-key-reused.
Thử lại trong khi yêu cầu đầu tiên vẫn đang chạy sẽ trả về 409 idempotency-in-progress; hãy thử lại sau một lát.
Phản hồi 5xx không được lưu, nên một lần thử lại sau lỗi máy chủ sẽ chạy lại.

Khóa có phạm vi theo bên gọi: tổ chức và khóa API (hoặc người dùng bảng điều khiển) đã gửi chúng. Các thao tác nhận khóa được đánh dấu bằng tham số header Idempotency-Key trong tài liệu tham khảo API, trong đó có tạo mẫu, tải tệp lên, xuất bản, tạo và hủy phong bì, gửi lại liên kết, tạo phiên ký, tạo liên kết ký và endpoint webhook, và gửi lại sự kiện.

Chống trùng lặp theo id của riêng bạn

Khóa lũy đẳng bảo vệ các lần thử lại của một yêu cầu. Để bảo đảm một đối tượng nghiệp vụ chỉ được gửi đúng một lần, hãy gửi thêm id của riêng bạn và dedupeOn:

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

Nếu đã tồn tại một phong bì với externalId đó (trong cùng chế độ), POST /v1/envelopes trả về phong bì đó với 200 và x-deduplicated: true thay vì tạo phong bì khác. Điều này đúng với mọi khóa, qua nhiều ngày và với các yêu cầu đồng thời.

Giới hạn tần suất

API có xác thực (khóa API) hiện không có giới hạn tần suất yêu cầu cố định; việc gửi bị giới hạn bởi gói của bạn. Giới hạn được áp dụng ở những nơi có thể bị lạm dụng:

Ở đâu	Giới hạn
`POST /v1/public/verify`	60 yêu cầu mỗi phút cho mỗi IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 yêu cầu mỗi phút cho mỗi IP
`GET /v1/sso/discover`	30 lượt tra cứu mỗi phút cho mỗi IP
Mã dùng một lần của người ký	5 mã mỗi 15 phút cho mỗi phiên; 5 lần thử cho mỗi mã
Gửi lại cho người nhận	Một lần mỗi phút cho mỗi người nhận
Liên kết luôn hoạt động	Theo từng liên kết: `perEmailPerDay` (mặc định 3), `perIpPerHour` (mặc định 20), `dailyCap` tùy chọn
Đăng nhập bảng điều khiển bằng mật khẩu	10 lần mỗi phút cho mỗi IP; 10 lần mỗi 15 phút cho mỗi địa chỉ email
Đăng ký bảng điều khiển bằng mật khẩu	5 lần mỗi phút cho mỗi IP; 5 lần mỗi giờ cho mỗi địa chỉ email
Email đặt lại mật khẩu	5 lần mỗi 15 phút cho mỗi IP; 3 lần mỗi giờ cho mỗi địa chỉ email
Mã đăng nhập bảng điều khiển	3 lần mỗi phút cho mỗi IP

Các endpoint công khai có giới hạn sẽ gửi các header RateLimit-Limit, RateLimit-Remaining và RateLimit-Reset (giây). Khi vượt giới hạn, API trả về 429 kèm một problem rate-limited, thường có header Retry-After tính bằng giây.