التعامل مع حدود المعدل وأخطاء الخادم

التعامل مع استجابة 429

يرد الطلب الذي تجاوز حد المعدل بالرمز 429 Too Many Requests وتكون قيمة detail.status هي rate_limit_exceeded. اقرأ ترويسات الاستجابة قبل إعادة المحاولة:

• يحدد Retry-After الحد الأدنى للانتظار بالثواني بعد رفض الطلب.
• يبيّن X-RateLimit-Limit حد مجموعة الطلبات.
• يبيّن X-RateLimit-Remaining عدد الطلبات المتبقية.
• يبيّن X-RateLimit-Reset وقت إعادة ضبط المجموعة.

انتظر المدة المحددة في Retry-After، ثم أعد المحاولة بتأخير أُسّي وعشوائية بسيطة. قلّل الطلبات المتوازية وضع العمل في طابور بدل إرسال دفعة فور إعادة ضبط النافذة.

التعامل مع أخطاء الخادم

عند استجابة 500، يحتوي المتن العام على خطأ عام وrequest_id، ولا يعرض تفاصيل الاستثناءات الداخلية. قد تعني 503 أن خدمة مطلوبة غير متاحة مؤقتًا.

أعد محاولة طلبات القراءة فقط مع حد أقصى للتأخير. قبل إعادة طلب إنشاء أو تحديث أو دفع أو أي طلب يغيّر الحالة، تحقق مما إذا اكتملت المحاولة الأولى. لا يثبت انتهاء المهلة أو استجابة 5xx فشل التغيير؛ وقد يؤدي التكرار الفوري إلى تكرار العمل.

الاحتفاظ ببيانات التشخيص

سجّل الوقت وطريقة الطلب ومساره وحالته ومتن الاستجابة وX-Request-Id. لا تسجّل قيمة x-api-key مطلقًا. أوقف إعادة المحاولة التلقائية بعد عدد قليل ومحدود من المحاولات، واعرض الفشل للمراجعة.