API keys, limits and errors

Public and secret keys

Public (pk_…)Secret (sk_…)
ForWeb pagesYour servers
Visible to othersYes: it is in your pageNever, if you keep it out of pages and apps
Protected byThe list of websites it may be used fromBeing secret
Sent asX-Atlas-Key header (the SDK does this)Authorization: Bearer sk_…
Refused whenUsed from a site not on its listPut 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

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;
  }
}
CodeStatusMeaning
missing_key401No API key was sent.
invalid_key401The key is unknown, revoked, or past its rotation grace period.
origin_not_allowed403A public key was used from a website not on its list.
secret_key_in_url401A secret key was sent in a URL. Send it in the Authorization header.
secret_key_in_browser403A secret key was sent from a browser. Use a public key there.
service_not_allowed403The key is not enabled for this service. Change it in the console.
rate_limited429Too many requests a minute. Wait for Retry-After seconds.
quota_exceeded429The 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_reached429A 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.
throttled429Unusual 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_token401A map tile request without a valid tile token. The SDK handles these.
token_expired401A tile token expired. The SDK fetches a new one by itself.
no_route404There is no route between the two points, or one is more than 2 km from a road.
not_found404No such place, feature or endpoint.
method_not_allowed405The endpoint exists but takes another method; the Allow header says which.
invalid422A parameter is missing or out of range; the message says which.
upstream_unavailable502A MilsatMaps service, such as search or directions, is unavailable. Retry shortly.
mode_unavailable503That kind of directions (walking, say) isn't offered here.
not_approved403The project hasn't been approved for that data layer (postcode units, say). Ask for it on the console's Data access page.
network_error0SDK only: MilsatMaps couldn't be reached at all, such as when the device is offline.