Errors

Every error has the same shape, written so an agent can act on it without a person:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Balance is 0, so requests are paused and nothing more will be charged. ...",
    "docs_url": "https://maprouter.dev/docs/errors#insufficient_credits"
  }
}

The code is stable; the message may be more specific than the one below. Errors never cost credits. Responses that ask you to wait carry Retry-After in seconds.

Code	Status	What to do
`insufficient_credits`	402	Balance is 0, so requests are paused and nothing more will be charged. Add credits in the dashboard, or ask the user to.
`key_cap_reached`	402	This key has reached its spending cap. Raise the cap in the dashboard, or wait for it to reset.
`missing_key`	401	No API key was sent. Pass it as "Authorization: Bearer <key>", or as ?key= for tiles and styles.
`invalid_key`	401	This API key is not recognised or has been revoked. Create a new key in the dashboard.
`origin_not_allowed`	403	This publishable key is not allowed on this origin. Add the origin to the key's allowed list.
`key_type_not_allowed`	403	Publishable (mr_pk_) keys cannot call this endpoint. Call it from your server with a secret (mr_sk_) key.
`invalid_request`	400	A parameter is missing or invalid. The message says which one and how to fix it.
`raise_not_allowed`	403	Agents can only lower budgets. Ask the user to raise it in the dashboard.
`not_found`	404	No such endpoint. See the API reference for the list of endpoints.
`request_too_large`	413	The request is larger than this endpoint allows. Split it into smaller requests.
`rate_limited`	429	Too many requests for this key. Wait for the number of seconds in Retry-After, then retry.
`feature_disabled`	503	This feature is temporarily unavailable. Retry after the number of seconds in Retry-After.
`internal_error`	500	Something failed on our side and nothing was charged for it. Retry in a few seconds.