أخطاء 429 وحدود الطلبات
كيف تعرف أي حد بلغته عند ظهور 429: حد الباقة (rate_limited) أم حد IP (Too Many Attempts) أم حدود صفحة رابط التتبع العامة أو مسارات الدخول أو رمز التحقق (OTP)، وماذا تفعل.
آخر تحديث 22 أكتوبر 2026 · آخر تحقق 22 أكتوبر 2026
ماذا يعني ذلك#
يعني رمز HTTP 429 («طلبات كثيرة جداً») أنك بلغتَ أحد الحدود، فلم يُنفَّذ الطلب: لا يُنشأ شيء ولا يُخصم شيء. وللمنصة عدة حدود مستقلة، وشكل الرد يبيّن أيّها بلغتَ.
من المتأثر#
المطورون الذين يستدعون /api/v1 (مفتاح التاجر) أو /api/company/v1 (مفتاح الشركة)، وزوار الصفحات العامة مثل صفحة رابط تتبع الطرد، ومن يسجّلون الدخول أو ينشئون حساباً، ومستخدمو تطبيقات الجوال.
الأسباب المحتملة#
| ما الذي يصلك | الحد الذي بلغتَه | يُحتسب لكل |
|---|---|---|
JSON فيه error.code بقيمة rate_limited وحقل error.retry_after وترويسة Retry-After |
حد باقتك للـ API بالدقيقة أو باليوم | حساب |
JSON بالشكل {"message": "Too Many Attempts."} مع Retry-After وX-RateLimit-Limit وX-RateLimit-Remaining |
حدود الـ IP: 60 طلباً في الدقيقة على كامل /api، ثم حدود المسارات مثل حد 60 المضبوط لـ POST /api/v1/parcels وحد 30 لـ GET /api/v1/statement، وتُبلَغ بعد نحو نصف هذا العدد من الطلبات (انظر أدناه) |
عنوان IP |
صفحة HTML: Too Many Requests received. Please try again later. مع مربع «سبب الخطأ» ومرجع يبدأ بالحرف H |
حدود الـ IP نفسها إذا خلا الطلب من Accept: application/json، وحدود الصفحات مثل صفحة رابط التتبع العامة /t/{tracking} (60 في الدقيقة) |
عنوان IP، أو المستخدم إن كان مسجّل الدخول |
نموذج الدخول: Too many login attempts. Please try again in N seconds. (والنص العربي «محاولات تسجيل دخول كثيرة جدًا. يرجى المحاولة مرة أخرى خلال: ثواني.» بلا رقم) |
5 محاولات فاشلة بالإيميل أو رقم الموبايل نفسه من عنوان IP واحد؛ ويُقفل الدخول نحو دقيقة. وتُحتسب المحاولات للحسابات غير الموجودة ولحسابات الشركة نفسها في موقعها. أما كلمة السر الخاطئة لحساب موجود في النوع الآخر من المواقع (مثل حساب شركة أو تاجر في النطاق المركزي) فتُرفض دون احتسابها | اسم الدخول وعنوان IP |
| طلبات تطبيقات الجوال (الردود نفسها أعلاه) | resend-otp 3 في الدقيقة؛ otp-verification وsignin وdeliveryman/login وlogin 10 في الدقيقة؛ register وpassword/email 5 في الدقيقة |
عنوان IP |
تسجيل التاجر في /join: «سجّلت حسابات كتيرة من هالجهاز اليوم — جرّب بكرا أو تواصل مع الدعم.» |
5 حسابات لكل جهاز في اليوم، و5 عمليات إرسال في الدقيقة | عنوان IP |
الشحن بدون حساب في /ship (نموذج الطلب): «طلبات كتيرة من جهازك — جرّب بعد N دقيقة.» |
إرسال الطلب 20 في اليوم لكل جهاز | عنوان IP |
الشحن بدون حساب في /ship (مربع السعر): «طلبات كتيرة — استنى دقيقة وجرّب.» وقد يطول الانتظار الفعلي حتى ساعة. أما الاستدعاء المباشر لفحص السعر فيعيد JSON فيه نص «طلبات كتيرة من جهازك — جرّب بعد N دقيقة.» |
فحص السعر 300 في الساعة لكل جهاز. ويظهر هذا النص القصير مع أي 429 على فحص السعر، ومنها حدود الدقيقة | عنوان IP |
أمور تستحق الانتباه:
- عدّادات الـ IP مشتركة. كل المسارات التي لها حد عادي بالدقيقة تضيف إلى عدّاد واحد لكل عنوان IP، أياً كان النطاق (domain) أو المضيف المستخدم في الطلب، فتشترك فيه كل المفاتيح والتطبيقات خلف العنوان العام نفسه. والمسارات التي لها حد خاص داخل مجموعة محدودة أصلاً تُحتسب مرتين:
POST /parcelsوGET /statementوPOST /webhooksواختبار الويب هوك (POST /webhooks/{id}/test) وPOST /parcelsفي واجهة الشركة. لذلك يكون المعدل الفعلي على هذه المسارات نحو نصف الحد المضبوط للمسار (مثلاً نحو 30 عملية إنشاء طرد في الدقيقة في واجهة التاجر)، ولا يزيد أبداً على 60 في الدقيقة المطبّقة على كل/api. - نوافذ ثابتة. تبدأ نافذة الدقيقة عند أول طلب محتسب. ويُصفَّر عدّاد الباقة اليومي عند الساعة 00:00 بتوقيت UTC.
- قيم الباقات. يُعبَّأ نموذج الباقة الجديدة مسبقاً بـ 60 في الدقيقة و5000 في اليوم (للتجار) أو 120 و20000 (للشركات). والقيمة الفارغة أو
0تعني بلا حد. - نص الرسالة. رسائل حد الباقة مترجمة، وقد يبدو نصها الإنجليزي ركيكاً، مثل
You have reached your plan limit: 60 order Per minute. Wait 42 seconds or upgrade your plan.أما النص العربي الافتراضي فهو «وصلت لحد باقتك: 60 طلب بالدقيقة. استنى 42 ثانية أو رقّي باقتك.».
كيف تشخّص المشكلة#
أعد الاستدعاء مع -i والترويسة Accept: application/json، ثم اقرأ المحتوى والترويسات:
curl -i https://YOUR_DOMAIN/api/v1/me \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"
- القيمة
rate_limitedتعني حد باقتك. يفتح التاجر «الباقة والاشتراك» ويقرأ «طلبات الـ API اليوم» تحت «استهلاكك من الباقة». ويقرأ مدير الشركة الاستهلاك في «الربط والـ API»، أو يستدعيGET /api/company/v1/me. - الرسالة
Too Many Attempts.تعني حد IP. قارنX-RateLimit-Limitبعدد الاستدعاءات في الدقيقة من عنوانك العام كله، بما فيها التطبيقات الأخرى. - صفحة HTML تعني أن الطلب خلا من ترويسة
Acceptالخاصة بـ JSON، أو أنه صفحة ويب. سجّل المرجعH…والوقت.
خطوات الحل#
انتظر انتهاء النافذة
توقف لعدد الثواني في
Retry-After(أوretry_after) ثم أعد المحاولة. وقد يعني الحد اليومي للباقة انتظار ساعات.خفّف السرعة ووزّع الاستدعاءات
أضف تأخيراً متغيراً بشكل عشوائي (jitter) بين الاستدعاءات، وتجنب تشغيل عدة عمليات معالجة (workers) من عنوان IP واحد. وخزّن مؤقتاً القوائم قليلة التغيّر مثل
/governoratesو/companies، واستخدم الويب هوك بدل الاستعلام المتكرر.أعد محاولة الإنشاء بأمان
أرسل
referenceمعPOST /parcelsليُعرَف الطلب المكرر. في واجهة التاجر يعيد تكرار الطلب الطرد الموجود (HTTP 200 مع"duplicate": true) بدل إنشاء طرد آخر. وفي واجهة الشركة يعيد المرجع نفسه للتاجر نفسه409معduplicate_reference: اعتبره «أُنشئ من قبل» واجلب الطرد بـGET /parcels/{reference}(ويبحث هذا الاستدعاء بين تجار شركتك كلهم، فإن كانوا قد يتشاركون المرجع نفسه فاستخدمGET /parcels?reference=…&merchant_id=…). وتفاصيل ذلك في مقالة إصدارات الواجهة وإعادة المحاولة.ارفع حد الباقة
إذا بلغت حد الباقة باستمرار فاطلب من المنصة نقلك إلى باقة بحدود أعلى. فحدود الباقات يضبطها السوبر أدمن لكل باقة، أما حدود الـ IP فثابتة ولا تُرفع لحساب بعينه.
متى تتواصل مع الدعم#
- إذا ظهر
429مع حجم طلبات قليل رغم أن نظامك وحده يستخدم عنوان الـ IP. - إذا لم يطابق عدّاد الاستهلاك في اللوحة استدعاءاتك.
- اذكر المرجع
H…والرابط والوقت عند الإبلاغ عن صفحة 429 بصيغة HTML.
API
GET /api/v1/mePOST /api/v1/parcelsPOST /api/company/v1/parcelsGET /api/company/v1/me