Hız limitleri ve idempotency

Idempotency

Bir POST isteğini yeniden denemeyi güvenli hâle getirmek için bir Idempotency-Key başlığı gönderin. Her işlem için yeni ve benzersiz bir değer kullanın (bir UUID veya onboarding-8841 gibi kendi sisteminizden bir kimlik): 1 ila 255 yazdırılabilir ASCII karakteri.

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

Bir anahtarla gelen ilk istek normal şekilde çalışır ve yanıtı 24 saat saklanır.
Aynı anahtar ve aynı istekle (yöntem, yol, sorgu ve gövde) yapılan bir yeniden deneme, saklanan yanıtı Idempotent-Replayed: true başlığıyla tekrar oynatılmış olarak alır.
Aynı anahtarın farklı bir istekle kullanılması 422 idempotency-key-reused döndürür.
İlk istek hâlâ çalışırken yapılan bir yeniden deneme 409 idempotency-in-progress döndürür; biraz sonra yeniden deneyin.
5xx yanıtları saklanmaz; bu nedenle bir sunucu hatasından sonraki yeniden deneme yeniden çalışır.

Anahtarlar çağırana göre kapsamlanır: onları gönderen kuruluş ve API anahtarı (veya panel kullanıcısı). Anahtar kabul eden işlemler API referansında bir Idempotency-Key başlık parametresiyle işaretlenmiştir; bunlar arasında şablon oluşturma, dosya yükleme, yayımlama, zarf oluşturma ve iptal etme, bağlantıları yeniden gönderme, imzalama oturumu oluşturma, imzalama bağlantısı ve webhook uç noktası oluşturma ve olayları yeniden teslim etme bulunur.

Kendi kimliğinize göre tekilleştirme

Idempotency anahtarları tek bir isteğin yeniden denemelerini korur. Bir iş nesnesinin yalnızca bir kez gönderildiğinden emin olmak için kendi kimliğinizi ve dedupeOn değerini de gönderin:

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

O externalId değerine sahip bir zarf zaten varsa (aynı modda), POST /v1/envelopes yeni bir zarf oluşturmak yerine mevcut zarfı 200 ve x-deduplicated: true ile döndürür. Bu durum anahtarlar, günler ve eşzamanlı istekler genelinde geçerlidir.

Hız limitleri

Kimliği doğrulanmış API’de (API anahtarları) bugün sabit bir istek hızı limiti yoktur; gönderim planınızla sınırlıdır. Limitler kötüye kullanımın mümkün olduğu yerlerde uygulanır:

Nerede	Limit
`POST /v1/public/verify`	IP başına dakikada 60 istek
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	IP başına dakikada 240 istek
`GET /v1/sso/discover`	IP başına dakikada 30 sorgu
İmzacı tek kullanımlık kodları	Oturum başına 15 dakikada 5 kod; kod başına 5 deneme
Alıcıya yeniden gönderme	Alıcı başına dakikada bir kez
Kalıcı bağlantılar	Bağlantı başına: `perEmailPerDay` (varsayılan 3), `perIpPerHour` (varsayılan 20), isteğe bağlı `dailyCap`
Panelde parolayla giriş	IP başına dakikada 10; e-posta adresi başına 15 dakikada 10
Panelde parolayla kayıt	IP başına dakikada 5; e-posta adresi başına saatte 5
Parola sıfırlama e-postaları	IP başına 15 dakikada 5; e-posta adresi başına saatte 3
Panel giriş kodları	IP başına dakikada 3

Limitli herkese açık uç noktalar RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset (saniye) başlıklarını gönderir. Limit aşıldığında API, genellikle saniye cinsinden bir Retry-After başlığıyla birlikte rate-limited sorunuyla 429 yanıtı verir.