تتعطل الشبكات في أسوأ موضع: بعد أن ينفّذ الخادم الإجراء وقبل أن يصلك الرد. ومفتاح عدم التكرار يجعل إعادة المحاولة آمنة.
كيف يعمل
يُنشئ العميل مفتاحًا فريدًا لإجراء واحد مقصود ويرسله مع الطلب. ويحفظ الخادم المفتاح مع النتيجة. فإن وصل المفتاح نفسه مرة أخرى، أعاد الخادم النتيجة المحفوظة بدل تنفيذ الإجراء من جديد.
تعمل مجموعة IETF HTTPAPI على توحيد ذلك في ترويسة الطلب Idempotency-Key (المسودة 08، أكتوبر 2026، ولم تصبح RFC بعد). وتصف المفتاح بأنه “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (ترجمة: قيمة فريدة يولّدها العميل، ويستخدمها المورد للتعرّف على المحاولات اللاحقة للطلب نفسه)، وتوصي باستخدام UUID أو معرّف عشوائي مماثل. وحالات الخطأ في المسودة:
| الحالة | الرمز |
|---|---|
| المفتاح غائب حيث يكون مطلوبًا | 400 Bad Request |
| الطلب الأصلي لا يزال قيد التنفيذ | 409 Conflict |
| إعادة استخدام المفتاح مع جسم مختلف | 422 Unprocessable Content |
وتقول AWS Builders’ Library الشيء نفسه من جهة العميل: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (ترجمة: واجهات API ذات الآثار الجانبية ليست آمنة لإعادة المحاولة ما لم توفّر عدم التكرار).
لماذا يهم
إعادة المحاولة مع التراجع الأُسّي ممارسة معتادة، وكثير من حزم SDK تعيد المحاولة تلقائيًا. ودون عدم التكرار، قد تُنشئ إعادة المحاولة بعد انتهاء المهلة طلبَي شراء أو خصمين. أما مع المفتاح فإعادة المحاولة آمنة أيًّا كان ما فعلته المحاولة الأولى. وهذا يجعله أداة أساسية للوكلاء والسكربتات التي تشتري أو تحجز أو تُنشئ أشياء دون إنسان يراقبها.
في BroadNet Inference
تستخدم BroadNet هذا النمط لشراء المفاتيح بالساعة. تقبل POST /portal/keys/hourly الحقل request_id في جسم JSON، ويقول التوثيق: “Idempotency is required for money safety” (ترجمة: عدم التكرار مطلوب لحماية المال):
curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
-H "Authorization: Bearer <portal-credential>" \
-H "Content-Type: application/json" \
-d '{"request_id":"order-20260920-001","label":"kiosk-1"}'
إعادة استخدام request_id لا تُنشئ مفتاحًا آخر ولا تخصم ثمنه. وبعد انتهاء المهلة، أو انقطاع الاتصال، أو استجابة 409 mint_in_progress، أو خطأ 5xx، أعد المحاولة بالقيمة نفسها لـ request_id. ويُرجع التكرار already_issued: true والاسم المستعار للمفتاح؛ ولا يحتوي على المفتاح الخام إلا أول استجابة ناجحة. ويقول التوثيق: “Never generate a replacement id until the original result is known.” (ترجمة: لا تولّد معرّفًا بديلًا قبل أن تُعرف النتيجة الأصلية).
لا توثّق BroadNet مفتاح عدم تكرار لـ /v1/chat/completions ولا للتفريغ الصوتي. راجع رموز الأخطاء وإعادة المحاولة لمعرفة ما يُعاد هناك، وحدود المعدل لتعرف لماذا قد تزيد إعادة المحاولة العمياء خطأ 429 سوءًا.