<!-- https://api.ibusisrael.online/docs/he/limits/ -->
# מגבלות ושגיאות

## מגבלות

| מי | בדקה (פרץ) | ביממה, 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/he/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/he/access/#codes).

## ניסיונות חוזרים

- נסו שוב רק בשגיאות רשת, `429`, `502`, `503` ו-`504`. אל תנסו שוב `4xx` אחרות: הבעיה בבקשה עצמה.
- כשיש `Retry-After`, המתינו את הזמן הזה; אחרת המתינו 1, 2, 4 שניות וכן הלאה, עם מעט אקראיות, ועצרו אחרי כמה ניסיונות.
- קוד תחנה לא מוכר אינו שגיאה בבקשת הגעות: התשובה היא `200` עם `source: "unknown_stop"` ורשימה ריקה.

## זמני המתנה

השער ממתין עד 12 שניות להגעות ועד 20 שניות ללוח זמנים יומי, ואז עונה `504`. הגדירו בלקוח זמן המתנה מעט ארוך יותר, למשל 15 עד 25 שניות.