Limits and errors

Limits#

Who	Per minute (burst)	Per day, UTC	Per month, UTC	At once	Heavy: per minute / day
Project, «trial»	30 (10)	1,000	20,000	2	—
Project, «standard»	120 (30)	20,000	400,000	4	—
Project, individual (example)	120 (30)	20,000	400,000	4	6 / 300
Without a key: older addresses only, per address (transition)	60 (30)	20,000	400,000	6	20 / 600

Limits belong to the project: all its keys share one budget. A new or rotated key does not add a budget, and neither do other addresses of the same data (app.ibusisrael.online, older paths).
Per minute with a short burst, per day and per month (reset at 00:00 UTC), requests at the same time, and a separate budget for heavy operations (only for projects that have them).
A request counts when it is admitted to the data. Refusals of the access check (401, 403, 429) do not count; our failures (502, 503, 504) are given back.
Keyed answers carry X-RateLimit-Limit and X-RateLimit-Remaining for the current minute. The developer cabinet shows the day and the month.
Without a key only the older addresses without /transport answer (transition); their limits apply per address: one IPv4 address or one IPv6 /64.
Over a limit: 429 with Retry-After and a code that names the limit (access errors). 503 with CAPACITY_RESERVED means the service keeps capacity for passengers: retry later.

Error format#

Every answer that is not 2xx has the same JSON body:

Error

{"code": "RATE_LIMITED", "detail": "", "source_state": null}

code is for your program, detail is a short technical hint (often empty), source_state is unavailable when a data source failed.

Error codes#

code	HTTP	What it means and what to do
`BAD_REQUEST`	400	A parameter has a wrong form (checked by the gateway). Fix the request; repeating it does not help.
`UPSTREAM_422`	422	A query parameter is missing or out of range (e.g. `limit=0`). Fix the request.
`NOT_FOUND`	404	The address is not a published path, or a code has a wrong form.
`UPSTREAM_404`	404	The object is not in the source (e.g. `Stop not found`, an alert that already ended).
`METHOD_NOT_ALLOWED`	405	Only GET and HEAD are accepted.
`RATE_LIMITED`	429	Too many requests per minute: of your project (with a key) or of your network (without a key). Wait `Retry-After` seconds.
`UPSTREAM_UNAVAILABLE`	502 / 503	An internal service or the data source is not reachable. Retry later with a growing pause.
`UPSTREAM_TIMEOUT`	504	The data source answered too slowly. Retry later.
`GATEWAY_BUSY`	503	The gateway is at its concurrency limit. Retry after a short pause.
`UPSTREAM_BAD_ANSWER`	502	The internal service answered something that is not valid JSON. Retry later; report it if it repeats.

Refusals of the access check (key, IP address, project, limits) have their own codes: access errors.

Retrying#

Retry only network errors, 429, 502, 503 and 504. Never retry other 4xx: the request itself is wrong.
Wait Retry-After when it is present, otherwise pause 1, 2, 4… seconds with some randomness, and stop after a few attempts.
An unknown stop code is not an error for arrivals: the answer is 200 with source: "unknown_stop" and an empty list.

Timeouts#

The gateway waits up to 12 seconds for arrivals and up to 20 seconds for a day timetable before it answers 504. Set your client timeout a little longer, for example 15–25 seconds.