درخواست تکرارپذیر

شبکه گاهی پاسخ را گم می‌کند. اگر درخواست ساخت پرداخت به تایم‌اوت خورد، نمی‌دانید پرداخت ساخته شده یا نه. با هر POST هدر Idempotency-Key را بفرستید تا تلاش دوباره با همان کلید، پاسخ اول را پس بگیرد و کار دو بار انجام نشود.

چطور کار می‌کند

• کلید هر رشته‌ای بین ۱ تا ۲۵۵ نویسه است. مقداری که از دادهٔ خودتان می‌سازید (order-1042، refund-1042-1) حتی بعد از راه‌اندازی دوبارهٔ سرور هم کار می‌کند؛ یک UUID تصادفی در یک فرایند.
• بزن به کارت اولین پاسخ هر کلید را ۲۴ ساعت نگه می‌دارد، همراه با اثری از متد، مسیر و بدنهٔ درخواست.
• همان کلید با همان درخواست، پاسخ ذخیره‌شده را با همان کد وضعیت و هدر Idempotent-Replayed: true برمی‌گرداند.
• همان کلید با بدنهٔ متفاوت با 400 idempotency_key_reused (نوع idempotency_error) رد می‌شود: هر کلید نام یک عملیات است.
• تلاش دوباره‌ای که وقتی درخواست اول هنوز در جریان است برسد، با 409 idempotency_key_in_use رد می‌شود. کمی صبر کنید و دوباره بفرستید.
• رسیدی که با multipart/form-data فرستاده می‌شود (POST /v1/payments/:id/receipts) با فیلدهایش و SHA-256 هر فایل شناخته می‌شود، نه با بدنهٔ خام. تلاش دوباره با مرز multipart تازه همان پاسخ اول را می‌گیرد و فایل‌های دیگر با همان کلید idempotency_key_reused می‌گیرند.
• درخواستی که در اعتبارسنجی رد شود (پارامتر ناقص یا نادرست) ذخیره نمی‌شود؛ می‌توانید درستش کنید و با همان کلید دوباره بفرستید. هر پاسخ دیگری، حتی خطای سرور، ذخیره و تکرار می‌شود.

کلیدها به حساب و حالت کلید API محدودند.

curl https://a.bezanbecard.com/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{"amount":12500000,"reference":"1042"}'

کتابخانه‌های رسمی

هر سه کتابخانه با هر POST یک Idempotency-Key می‌فرستند و خطای شبکه، تداخل 409، 429 و پاسخ‌های 5xx را به‌طور پیش‌فرض دو بار با همان کلید و فاصلهٔ رو به افزایش دوباره امتحان می‌کنند. فقط وقتی تلاش دوباره ممکن است از فرایند دیگری بیاید، مثل یک کار صف، کلید را خودتان بدهید.

آنچه پوشش نمی‌دهد

• درخواست‌های GET و DELETE کلید لازم ندارند: دو بار خواندن چیزی را عوض نمی‌کند و دو بار حذف کردن همان پاسخ را می‌دهد.
• POST /v1/connect/exchange کلید ذخیره نمی‌کند: کد یک‌بارمصرفش خودش محافظ است. افزونه‌ای که پاسخ را گم کند دوباره وصل می‌شود.
• درخواست تکرارپذیر جلوی تکرار کار با تلاش‌های دوبارهٔ شما را می‌گیرد، نه جلوی اینکه دو کلید متفاوت برای یک سفارش دو پرداخت بسازند. پرداخت باز سفارش را دوباره به کار ببرید یا کلید را از روی سفارش بسازید، همان‌طور که افزونه‌های فروشگاهی می‌کنند.