الحدود والأخطاء
الحدود#
| مَن | في الدقيقة (دفعة) | في اليوم، UTC | في الشهر، UTC | في الوقت نفسه | الثقيلة: في الدقيقة / اليوم |
|---|---|---|---|---|---|
| مشروع، «تجريبي» | 30 (10) | 1,000 | 20,000 | 2 | — |
| مشروع، «قياسي» | 120 (30) | 20,000 | 400,000 | 4 | — |
| مشروع، مخصّص (مثال) | 120 (30) | 20,000 | 400,000 | 4 | 6 / 300 |
| بدون مفتاح: العناوين القديمة فقط، لكل عنوان (فترة انتقالية) | 60 (30) | 20,000 | 400,000 | 6 | 20 / 600 |
- الحدود تخص المشروع: تتقاسم كل مفاتيحه ميزانية واحدة. المفتاح الجديد أو المستبدَل لا يضيف ميزانية، ولا تضيفها العناوين الأخرى للبيانات نفسها (
app.ibusisrael.onlineوالمسارات القديمة). - في الدقيقة مع دفعة قصيرة، وفي اليوم وفي الشهر (تتجدد عند 00:00 UTC)، والطلبات في الوقت نفسه، وميزانية منفصلة للعمليات الثقيلة (للمشاريع التي مُنحت لها فقط).
- يُحتسب الطلب عند قبوله للبيانات. رفض فحص الوصول (
401و403و429) لا يُحتسب؛ وأعطالنا (502و503و504) تُعاد إلى الميزانية. - ردود الطلبات ذات المفتاح تتضمن
X-RateLimit-LimitوX-RateLimit-Remainingللدقيقة الحالية. اليوم والشهر يظهران في صفحة المطوّر. - بدون مفتاح تجيب فقط العناوين القديمة بدون
/transport(فترة انتقالية)؛ وتُطبَّق حدودها على العنوان: عنوان IPv4 واحد أو شبكة IPv6 /64 واحدة. - عند تجاوز حد:
429معRetry-Afterورمز يسمّي الحد (أخطاء الوصول).503معCAPACITY_RESERVEDيعني أن الخدمة تحتفظ بالموارد للركاب: أعد المحاولة لاحقًا.
صيغة الخطأ#
لكل رد ليس 2xx جسم JSON نفسه:
{"code": "RATE_LIMITED", "detail": "", "source_state": null}code لبرنامجك، وdetail تلميح تقني قصير (غالبًا فارغ)، وsource_state يساوي unavailable عندما يتعطل مصدر بيانات.
رموز الأخطاء#
| code | HTTP | المعنى وما العمل |
|---|---|---|
BAD_REQUEST | 400 | معامل بصيغة خاطئة (فحص البوابة). صحّح الطلب، فالتكرار لن يفيد. |
UPSTREAM_422 | 422 | معامل الاستعلام مفقود أو خارج النطاق (مثل limit=0). صحّح الطلب. |
NOT_FOUND | 404 | المسار غير موجود أو أن الرمز بصيغة خاطئة. |
UPSTREAM_404 | 404 | العنصر غير موجود في المصدر (مثل Stop not found أو تنبيه انتهى). |
METHOD_NOT_ALLOWED | 405 | تُقبل طلبات GET وHEAD فقط. |
RATE_LIMITED | 429 | طلبات كثيرة في الدقيقة - لمشروعك (مع مفتاح) أو لشبكتك (بدون مفتاح). انتظر Retry-After ثانية. |
UPSTREAM_UNAVAILABLE | 502 / 503 | خدمة داخلية أو مصدر البيانات غير متاح. أعد المحاولة لاحقًا مع زيادة فترة الانتظار. |
UPSTREAM_TIMEOUT | 504 | استجاب مصدر البيانات ببطء شديد. أعد المحاولة لاحقًا. |
GATEWAY_BUSY | 503 | البوابة في حدّها الأقصى للطلبات المتزامنة. أعد المحاولة بعد توقف قصير. |
UPSTREAM_BAD_ANSWER | 502 | أعادت الخدمة الداخلية ردًا ليس JSON صالحًا. أعد المحاولة، وإن تكرر فأبلغنا. |
لرفض فحص الوصول (المفتاح، عنوان IP، المشروع، الحدود) رموزه الخاصة: أخطاء الوصول.
إعادة المحاولة#
- أعد المحاولة فقط عند أخطاء الشبكة و
429و502و503و504. لا تُعد المحاولة مع أخطاء4xxالأخرى: المشكلة في الطلب نفسه. - إذا وُجد
Retry-Afterفانتظر المدة المذكورة؛ وإلا فانتظر 1 ثم 2 ثم 4 ثوانٍ مع قليل من العشوائية، وتوقف بعد بضع محاولات. - رمز محطة غير معروف ليس خطأ في طلب مواعيد الوصول: الرد
200معsource: "unknown_stop"وقائمة فارغة.
مهلات الانتظار#
تنتظر البوابة مواعيد الوصول حتى 12 ثانية وجدول اليوم حتى 20 ثانية، ثم تجيب 504. اجعل مهلة العميل أطول قليلًا، مثل 15 إلى 25 ثانية.