API keys, limits and errors
Public and secret keys
| Public (pk_…) | Secret (sk_…) | |
|---|---|---|
| For | Web pages | Your servers |
| Visible to others | Yes: it is in your page | Never, if you keep it out of pages and apps |
| Protected by | The list of websites it may be used from | Being secret |
| Sent as | X-Atlas-Key header (the SDK does this) | Authorization: Bearer sk_… |
| Refused when | Used from a site not on its list | Put in a URL, or sent from a browser |
Each key is either test or live. They work the same way; the label helps you keep development keys out of production.
Websites a public key may be used from
Each entry is a scheme and host, with an optional port: https://www.example.com. A leading *. covers every subdomain but not the domain itself, so list both if you need both. A port of * covers any port, which suits http://localhost:* during development. Requests whose page is not on the list are refused with origin_not_allowed.
Rotating and revoking
In the console, Rotate makes a new key with the same settings and lets the old one keep working for 24 hours or 7 days while you switch over, or stops it straight away. Revoke stops a key for good. Either takes effect within a minute.
We keep only a fingerprint of each key, so a key is shown once, when it is made. If you lose one, rotate it.
Limits
- Monthly allowance, per project and shared by all its keys, set by the project's plan. Each map load, search, place lookup or route that is answered is one request; one refused or failed (a bad parameter, nothing found, an outage) is not counted. On the Free plan, requests stop at the allowance with
quota_exceededuntil the first of the next month (UTC). On a paid plan they carry on, billed per 1,000 at the start of the next month, up to the spending cap you set in the console; at the cap they stop withspend_cap_reacheduntil the 1st, or until the owner raises the cap. The console shows how much is left.
A map load is a map opening on a page: onenew milsat.Map, however much it's then panned and zoomed and however many tiles it draws. A map left open renews itself for free for up to 12 hours; maps on the same page share one load. - Rate limits, per key: a ceiling per minute for the key (600 by default), and a lower one for any single visitor (300 by default). Over either, requests are refused with
rate_limitedand aRetry-Afterheader saying how many seconds to wait. Contact us to raise them. - Zoom: MilsatMaps' own layer appears from zoom 8, roughly a city. Below that you see the base map only.
Errors
The SDK rejects with a MilsatError carrying the HTTP status, a stable code, and a message for people. The REST API answers { "error": { "code": "…", "message": "…" } }.
try {
await milsat.directions(from, to);
} catch (error) {
if (error instanceof milsat.MilsatError && error.code === "no_route") {
showMessage("We could not find a road between those places.");
} else {
throw error;
}
}| Code | Status | Meaning |
|---|---|---|
missing_key | 401 | No API key was sent. |
invalid_key | 401 | The key is unknown, revoked, or past its rotation grace period. |
origin_not_allowed | 403 | A public key was used from a website not on its list. |
secret_key_in_url | 401 | A secret key was sent in a URL. Send it in the Authorization header. |
secret_key_in_browser | 403 | A secret key was sent from a browser. Use a public key there. |
service_not_allowed | 403 | The key is not enabled for this service. Change it in the console. |
rate_limited | 429 | Too many requests a minute. Wait for Retry-After seconds. |
quota_exceeded | 429 | The project has used its monthly allowance and has no overage (the Free plan, or a cap of zero). Requests resume on the 1st. |
spend_cap_reached | 429 | A paid project has used its allowance and all the overage its spending cap allows. Requests resume on the 1st, or as soon as the owner raises the cap. |
throttled | 429 | Unusual activity from one address, such as sweeping the map tile by tile: requests from it are slowed for an hour. Contact us if this is a mistake. |
invalid_token | 401 | A map tile request without a valid tile token. The SDK handles these. |
token_expired | 401 | A tile token expired. The SDK fetches a new one by itself. |
no_route | 404 | There is no route between the two points, or one is more than 2 km from a road. |
not_found | 404 | No such place, feature or endpoint. |
method_not_allowed | 405 | The endpoint exists but takes another method; the Allow header says which. |
invalid | 422 | A parameter is missing or out of range; the message says which. |
upstream_unavailable | 502 | A MilsatMaps service, such as search or directions, is unavailable. Retry shortly. |
mode_unavailable | 503 | That kind of directions (walking, say) isn't offered here. |
not_approved | 403 | The project hasn't been approved for that data layer (postcode units, say). Ask for it on the console's Data access page. |
network_error | 0 | SDK only: MilsatMaps couldn't be reached at all, such as when the device is offline. |