Beta

Errors

Today: live. Every endpoint on maps-api.ranamaps.com answers errors this way. Rana's own endpoints on api.ranamaps.com are not part of the developer platform.

The error body

An error is an HTTP status plus a JSON body:

{
  "error": "scope_not_allowed",
  "message": "This key cannot be used for directions. Add the directions scope to the key in Studio.",
  "docs": "https://developers.ranamaps.com/errors#scope_not_allowed"
}

• error is a stable code. Branch on it. It never changes within v1.
• message is plain English for you, the developer. Do not show it to your users, and do not parse it: the wording can change.
• docs links to the code's entry below.
• Some errors add fields, for example details on invalid_body. Ignore fields you do not know.
• Quote the Rana-Request-Id header when you write to us about a failed request.

"Nothing found" is not an error. A search with no result answers 200 with an empty list.

Codes

invalid_request (400). A parameter is missing or out of range. The message names it. Fix the request; retrying the same one will fail again.

invalid_body (400). The JSON body does not match the schema. details lists the fields.

conflicting_keys (400). The ?key= parameter and the X-Rana-Key header hold different keys. Send one.

too_many_cells (400). A distance matrix asked for more than 100 cells (origins × destinations). Split it.

too_many_points (400). Too many points for snap to roads, or too many waypoints. Split the trace.

missing_key (401). No key was sent. See keys and security.

malformed_key (401). The key is not in the pk_live_… or sk_live_… form. Check for a missing character or a stray space.

unknown_key (401). No such key.

revoked (403). The key was revoked in Studio. Make a new one.

organisation_suspended (403). Your organisation is suspended. Write to hello@ranamaps.com.

client_not_allowed (403). This public key does not list the web origin, Android app or iOS bundle id that sent the request. Add it in Studio.

no_client_identity (403). A public key was sent with no origin, package or bundle id. Use a secret key on servers.

secret_key_in_browser (403). A secret key was sent from a browser. Treat it as leaked: revoke it now and use a public key in the page.

scope_not_allowed (403). The key does not hold the scope for this product. Add the scope in Studio, or use another key.

not_found (404). No such resource, for example a place id that does not resolve.

rate_limited (429). Your organisation is over its per-minute limit. Wait the number of seconds in Retry-After, then try again. See limits and usage.

daily_limit_reached (429). Your organisation used its daily allowance for this product. It resets at 00:00 UTC (01:00 in Lagos). Ask us for a higher plan.

spending_cap_reached (429). Your organisation reached the monthly spending cap it agreed with us. Requests resume next month, or when we raise the cap. Write to hello@ranamaps.com.

internal_error (500). Our fault. Retry once after a short wait.

upstream_unavailable (503). Routing or search is busy or down. Wait the number of seconds in Retry-After.

timeout (504). The answer took too long. Try a smaller request.

Retrying

Retry only 429, 500, 503 and 504. Wait Retry-After seconds when it is sent; otherwise wait 1 second, then 2, then 4, and stop after 4 tries. Never retry 400, 401, 403 or 404 unchanged.

In the SDKs

Every SDK throws or returns one error type, RanaError, with the code (the error field above), the message, the HTTP status and the requestId. Map data in a successful answer always comes with "© Rana Maps © OpenStreetMap".