Rate limits and budgets

Rate limits

Every key has a per-second limit with a short burst allowance, set by your organization's plan. Every /v1 response carries the current state in the RateLimit headers (IETF draft): q requests per w seconds with a burst of burst; r requests remain, the window resets in t seconds.

RateLimit: "key";r=19;t=1
RateLimit-Policy: "key";q=10;w=1;burst=20

Over the limit the API answers 429 rate_limited with Retry-After (seconds). Wait that long, then retry; the SDKs never retry a 429 in a tight loop. Map tiles are not rate-limited per request: they are covered by the map session.

What is counted

Usage is counted per key, per product and per day (Asia/Almaty), and shown in the console under Usage & budgets, where it can be exported as CSV. Each endpoint in the API reference lists what it counts:

Retries with the same Idempotency-Key, refused requests and cached answers are not counted twice.

Plans and quotas

Each plan includes a set of products (scopes), a rate limit and monthly quotas per product. A key only gets the products its plan includes — a free plan never gets paid results, not even from a cache (403 scope_denied). When a monthly quota is used up, plans either refuse further calls (429 quota_exceeded) or bill per use. Your plan and its limits are shown in the console; the final prices and quotas are being set and are listed on the pricing page.

Budgets

Budgets protect you from unexpected costs. They belong to the organization, never to a single key:

• an organization cap in money (tenge) per month;
• a cap per product in units (for example traffic tiles).

Owners and billing members set caps in the console. Paid calls are reserved against the budget before the provider is called, so a cap is never exceeded, even under load. When a cap is reached:

• routing falls back to a route without live traffic and says so in traffic.reason;
• live traffic tiles answer 204 with X-Traffic-Status: budget_exhausted (the map keeps working without traffic);
• where no degraded answer exists the API returns 402 budget_exhausted;
• if the budget service itself is unavailable, paid calls are refused (503 budget_unavailable) rather than risking an overrun.

The console warns when usage gets close to a cap.

Keys: rotation and revocation

• Rotate a key in the console to get a new secret; the old one keeps working for the grace period you choose (none, 1 hour, 24 hours or 7 days), so you can deploy the new key without downtime.
• Revoke stops a key everywhere within 1 minute (API and map tiles).