Errors & Limits

On this page

All Maptoolkit APIs report errors the same way and share one quota model. This page collects both in one place. Each API page lists the error messages specific to that API.

Error format

An error returns an HTTP status code and a short plain-text message in the body, not JSON. Read the body as text before you parse it.

HTTP/1.1 403 Forbidden
Content-Type: text/plain

Api-key not found!

Some APIs pass errors from the engine behind them through unchanged, for example the routing engine or the geocoder. Those messages are not listed in the docs, so always log the body.

Status codes

Status	Meaning
`400`	The request is not valid: a parameter is missing or cannot be parsed, or the engine behind the API rejected it. The body says which.
`403`	The API key is missing, not recognized, or has no access to this service. See API key errors.
`404`	The resource does not exist, for example a tile outside a style’s coverage area.
`500`	Internal server error. Retry later, and contact us if it persists.

API key errors

Body	Cause	Fix
`Access denied!`	The request has no API key.	Add `api_key=YOUR_API_KEY` or the `MTK-ApiKey` header. See First Steps.
`Api-key not found!`	The key does not exist.	Check that the key is copied completely, with no spaces.
`Api-key not authorized!`	The key exists but has no access to this service.	Check which APIs your plan includes, or contact us.

A key restricted to certain referers or user agents is also refused when a request comes from somewhere else. See Restrict your key.

Request quotas

Limits are monthly request quotas tied to your plan, not a rate per second. Current allowances are on the pricing page.

The free Basic plan has a hard limit. Requests are refused once it is reached.
On Pro and Ultra, requests past the allowance are billed rather than refused.
Enterprise plans have no request limit.

Requests are counted in two separate allowances:

Allowance	What counts	Rate
Tile requests	Vector, raster and terrain tiles	Lower rate per request
API requests	Every other API: routing, isochrones, map matching, geocoding, elevation, weather and route enhancement	Higher rate per request

A typical interactive map uses both: the basemap uses tile requests, and a route or search on the map uses API requests.

The APIs return no RateLimit-* or Retry-After headers, so a client cannot read its remaining quota from a response.

Per-request limits

API	Limit
Isochrone API	`time` is at most 60 minutes.
Map Matching API	Tracks longer than a maximum length are refused with a `400`.
Route Enhancement API	A `POST` body can be up to 50 MB.
Routing Enhancement API	A `POST` body can be up to 50 MB.
Weather API	Forecasts reach up to 120 hours ahead.

Errors by API

Each API page lists the messages you are most likely to see: