مواد پر جائیں
bona fidedocs

ریٹ لمٹس اور idempotency

Idempotency

سیکشن کا عنوان «Idempotency»

کسی POST کو دوبارہ کوشش کے لیے محفوظ بنانے کے لیے اس پر Idempotency-Key ہیڈر بھیجیں۔ ہر آپریشن کے لیے ایک نئی، منفرد ویلیو استعمال کریں (ایک UUID، یا آپ کے اپنے سسٹم کی کوئی id جیسے onboarding-8841): 1 سے 255 قابلِ طباعت ASCII حروف۔

Terminal window
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 گھنٹوں کے لیے محفوظ کیا جاتا ہے۔
  • اسی کلید اور اسی درخواست (میتھڈ، پاتھ، query اور باڈی) کے ساتھ دوبارہ کوشش پر محفوظ شدہ جواب Idempotent-Replayed: true ہیڈر کے ساتھ دوبارہ ملتا ہے۔
  • اسی کلید کے ساتھ مختلف درخواست 422 idempotency-key-reused ہے۔
  • پہلی درخواست کے چلتے ہوئے دوبارہ کوشش 409 idempotency-in-progress ہے؛ تھوڑی دیر بعد دوبارہ کوشش کریں۔
  • 5xx جوابات محفوظ نہیں کیے جاتے، اس لیے سرور ایرر کے بعد دوبارہ کوشش پھر سے چلتی ہے۔

کیز کا دائرہ کالر تک محدود ہے: تنظیم اور وہ API کلید (یا ڈیش بورڈ صارف) جس نے انہیں بھیجا۔ جو آپریشنز کلید قبول کرتے ہیں وہ API حوالے میں Idempotency-Key ہیڈر پیرامیٹر سے نشان زد ہیں، جن میں ٹیمپلیٹس بنانا، فائلیں اپ لوڈ کرنا، شائع کرنا، لفافے بنانا اور کالعدم کرنا، لنکس دوبارہ بھیجنا، دستخط کے سیشنز بنانا، دستخط کے لنکس اور webhook اینڈ پوائنٹس بنانا، اور ایونٹس دوبارہ بھیجنا شامل ہیں۔

اپنی id کے ذریعے ڈپلیکیٹ سے بچاؤ

سیکشن کا عنوان «اپنی id کے ذریعے ڈپلیکیٹ سے بچاؤ»

Idempotency کیز ایک درخواست کی دوبارہ کوششوں کی حفاظت کرتی ہیں۔ یہ یقینی بنانے کے لیے کہ کوئی کاروباری آبجیکٹ صرف ایک ہی بار بھیجا جائے، اپنی 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 problem جواب دیتا ہے، عام طور پر سیکنڈز میں Retry-After ہیڈر کے ساتھ۔