Rate limits & quotas

Navvo applies three kinds of limit to keep the platform fast and fair:

• Key quota: how many requests each API key may make per minute and per day.
• Per-IP limit: how many keyed requests may come from one client IP address per minute and per day.
• Request throttle: how many requests one client IP address may send to one endpoint per minute, with or without a key.

All windows are fixed, not rolling. A minute is a clock minute: its counters start again at second :00 of every minute. A day is a UTC day: its counters start again at 00:00 UTC.

Default limits

Key quotas

Each key has its own per-minute and per-day quota. A new key takes its plan's limits unless you set quotaPerMinute / quotaPerDay yourself: free gives 60 a minute and 5,000 a day, starter 255 and 100,000, and growth, scale and enterprise 255 a minute with 1,000,000, 8,000,000 and 10,000,000 a day. In the Developer Portal and the developer API you can set up to 255 requests per minute and 10,000,000 per day: that is the self-serve cap. Keys set up by Navvo can have higher limits, or be unlimited.

Every request the key sends to an endpoint that needs a scope counts as one against its quota, whatever the endpoint. Request weights apply to monthly billing only (see plans & metering).

Per-IP limits

The per-IP limit applies only to requests that send an API key to an endpoint that needs a scope. Navvo counts these requests per client IP address, across every key used from that address. Each request is checked against the platform limit (90 per minute, 30,000 per day) or the sending key's own quota, whichever is higher. A key that is the only one used from its address is therefore never held below its own quota. When several keys send from one address, they share one count, so their combined traffic can reach the per-IP limit before each key reaches its own quota: send each key from its own address, or use one key with a quota that covers the combined traffic. Requests from an unlimited key are neither counted nor checked.

Requests without a key are not subject to the per-IP limit. They are covered by the request throttle.

Request throttle

Every endpoint allows each client IP address up to 3,000 requests per minute, with or without a key. Some endpoints set a tighter limit of their own: for example, the street-imagery nearest-image and sequence lookups allow 60 per minute, and search events allow 60 per minute. A few map-tile layers that a moving map fetches in bursts are never throttled, so a map that is drawing is never refused.

Over the limit, the endpoint answers 429 Too Many Requests with code RATE_LIMITED and a Retry-After header that gives the number of seconds to wait.

Plans

Keys carry a plan tier that determines available quota:

The plan keys are free, starter, growth, scale, and enterprise (the legacy startup value now maps to starter). When you create or update a key without explicit quotas, it adopts the matching plan's default quotaPerMinute / quotaPerDay. See the plan catalog for pricing and included requests.

Response headers

When a request sends a key to an endpoint that needs a scope, the response reports where the key stands against its quota:

These headers describe the key's own quota, not the per-IP limit.

Responses from throttled endpoints also report the request throttle for your IP address on that endpoint:

Browser code on any site can read all of these headers (see Conventions → Cross-origin).

When you exceed a limit

Key quota or per-IP limit: 403 QUOTA_EXCEEDED

Requests over a key quota or a per-IP limit are refused with HTTP 403 and code QUOTA_EXCEEDED. The details object says which limit was hit:

{
  "statusCode": 403,
  "message": "API key quota exceeded for scope routing: 180/minute",
  "error": "Forbidden",
  "code": "QUOTA_EXCEEDED",
  "details": { "scope": "routing", "limit": 180, "window": "minute", "observed": 181, "retryAfterSeconds": 23 },
  "requestId": "847c7a9b-a7c8-4b61-b138-d4e6b585626a"
}

The four messages you may see are API key quota exceeded for scope …: …/minute, API key quota exceeded for scope …: …/day, IP rate limit exceeded: …/minute and IP daily quota exceeded: …/day. Branch on code and details, not on the message.

Request throttle: 429 RATE_LIMITED

Requests over the request throttle get HTTP 429 with code RATE_LIMITED. Wait the number of seconds in the Retry-After header before you send to that endpoint again.

Unlimited keys

Navvo can mark a key unlimited, for example for a partner whose servers make requests for many users. You can't set this yourself, in the portal or over the API: contact Navvo. An unlimited key carries "unlimited": true in its key object and shows an Unlimited badge in the Developer Portal.

An unlimited key is not held to:

• its per-minute and per-day quota. quotaPerMinute and quotaPerDay are kept but not enforced, and they apply again if Navvo switches unlimited off;
• the per-IP minute and day limits. Its requests are neither counted towards them nor checked against them, so they can't push other keys used from the same address over either;
• the request throttle of 3,000 requests per minute, on endpoints that need an API-key scope and set no tighter limit of their own;
• the 60 requests per minute limit of POST /search/events.

These still apply to an unlimited key:

• revocation, scopes, and the websites and IP addresses the key is restricted to;
• any block Navvo has placed on an IP address because of abuse;
• endpoints with an anti-abuse limit of their own, such as the street-imagery nearest-image and sequence lookups (60 per minute per IP address), the AI helper endpoints (30 per minute) and public forms;
• the 3,000 per minute request throttle on endpoints that don't need an API-key scope, such as sign-in, account endpoints and the AI assistant;
• request-size limits, such as the number of matrix pairs, 50 addresses per batch geocode, the number of optimization stops and body sizes.

Unlimited lifts Navvo's per-key and per-address caps. It does not lift the capacity of the service, so talk to Navvo before you send sustained very high volumes.

How responses show it. On endpoints that need a scope, every response carries:

x-navvo-quota-limit-minute: unlimited
x-navvo-quota-remaining-minute: unlimited
x-navvo-quota-limit-day: unlimited
x-navvo-quota-remaining-day: unlimited
x-navvo-quota-unlimited: true

Endpoints where the request throttle is lifted send no X-RateLimit-* headers. An unlimited key never receives QUOTA_EXCEEDED.

Usage is still counted. The key's usage meters in the portal keep counting requests this minute and today, with no ceiling. GET /developer/api-keys/:id/usage returns "unlimited": true with minute.limit and day.limit set to null. Every request is still metered by weight and billed as usual.

When Navvo makes a key unlimited or limits it again, the change takes effect within about a minute.

Best practices