<!-- https://api.ibusisrael.online/docs/ru/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/ru/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/ru/access/#codes).

## Повторы

- Повторяйте только сетевые ошибки, `429`, `502`, `503` и `504`. Другие `4xx` не повторяйте: ошибка в самом запросе.
- Если есть `Retry-After`, ждите столько; иначе паузы 1, 2, 4… секунды с небольшой случайностью, и остановитесь после нескольких попыток.
- Неизвестный код остановки для прибытий - не ошибка: ответ `200` с `source: "unknown_stop"` и пустым списком.

## Тайм-ауты

Шлюз ждёт прибытия до 12 секунд, дневное расписание - до 20 секунд, затем отвечает `504`. Ставьте в клиенте тайм-аут чуть больше, например 15-25 секунд.