# الحدود والأخطاء ## الحدود | مَن | في الدقيقة (دفعة) | في اليوم، 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` للدقيقة الحالية. اليوم والشهر يظهران في [صفحة المطوّر](https://app.ibusisrael.online/developers). - بدون مفتاح تجيب فقط العناوين القديمة بدون `/transport` (فترة انتقالية)؛ وتُطبَّق حدودها على العنوان: عنوان IPv4 واحد أو شبكة IPv6 /64 واحدة. - عند تجاوز حد: `429` مع `Retry-After` ورمز يسمّي الحد ([أخطاء الوصول](/docs/ar/access/#codes)). `503` مع `CAPACITY_RESERVED` يعني أن الخدمة تحتفظ بالموارد للركاب: أعد المحاولة لاحقًا. ## صيغة الخطأ لكل رد ليس 2xx جسم JSON نفسه: ```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، المشروع، الحدود) رموزه الخاصة: [أخطاء الوصول](/docs/ar/access/#codes). ## إعادة المحاولة - أعد المحاولة فقط عند أخطاء الشبكة و`429` و`502` و`503` و`504`. لا تُعد المحاولة مع أخطاء `4xx` الأخرى: المشكلة في الطلب نفسه. - إذا وُجد `Retry-After` فانتظر المدة المذكورة؛ وإلا فانتظر 1 ثم 2 ثم 4 ثوانٍ مع قليل من العشوائية، وتوقف بعد بضع محاولات. - رمز محطة غير معروف ليس خطأ في طلب مواعيد الوصول: الرد `200` مع `source: "unknown_stop"` وقائمة فارغة. ## مهلات الانتظار تنتظر البوابة مواعيد الوصول حتى 12 ثانية وجدول اليوم حتى 20 ثانية، ثم تجيب `504`. اجعل مهلة العميل أطول قليلًا، مثل 15 إلى 25 ثانية.