الخلاصة

  • تحفظ Stripe في طلبات POST على API v1 رمز الاستجابة وجسمها بعد بدء تنفيذ النقطة، حتى إن كان الرمز 500. يعيد المفتاح نفسه هذه الاستجابة ما دام سجله محفوظاً.
  • نتيجة 500 غير محسومة؛ قد تكون للعملية آثار. قد تنتج التسوية كائناً ويصل إشعاره عبر webhook من دون أن يتغير الرد المحفوظ. تختلف آلية إعادة المحاولة في API v2.

العميل ينتظر جواباً، والرد القديم يعود

يطلب العميل تأكيد عملية لم تصله نتيجتها. يرى فريق الدعم 500 ثم يكرر الطلب بالمفتاح نفسه، فيعود 500. في API v1 قد تكون الاستجابة الثانية نسخة من الأولى. تحفظ Stripe أول نتيجة بعد بدء التنفيذ؛ وتكشف Idempotent-Replayed: true أن الرد أُعيد من السجل. الخطأان على الشاشة لا يجيبان عن سؤال العميل: هل نشأ الكائن أم لا؟

المشكلة أن 500 لا يغلق ملف العملية. تقول Stripe إن آثاراً قد تكون حدثت. خلال التعافي من حادث، تحاول تسوية الأعمال الفاشلة وقد ترسل webhook لكائن أُنشئ أثناء التسوية. يبقى الرد المخزن كما كان، وقد لا تنجح التسوية أصلاً. لذلك يحتاج المشغّل إلى سجلين متوازيين: الرد الذي وصل، وحالة الكائن التي تُثبت لاحقاً.

يبدأ الربط بمعرّف محلي للعملية يُنشأ قبل الاتصال الأول ويوضع في بيانات المورد الوصفية. بعد 500 يبحث الفريق عن الكائن، ويفحص الطلب في Dashboard، ثم يطابق إشعارات webhook بعد التحقق من توقيعها. إذا ظل المصير مجهولاً، فقد يبدأ مفتاح جديد عملية منفصلة. يحتاج الدعم والمالية والهندسة إلى المعرّف نفسه حتى يسمع العميل جواباً واحداً.

تضيف نسخة API فرقاً جوهرياً. تصف Stripe في v2 إعادة محاولة لا تكرر العمل الذي نجح، وتسعى إلى إكمال العمل الفاشل أو الجزئي حيث يمكن، مع رد محدث. خطة الانتقال من v1 إلى v2 يجب أن تحدد معنى المحاولة التالية، لا أن تكتفي بتغيير مكتبة العميل.

المصادر