API reference
Errors & limits
Status codes, the error format, limits, and the headers that tell you how many usage units are left.
Error format
Every error has the same JSON shape:
{"error":{"status":400,"message":"Parameter 'q' needs at least 2 characters."}}Status codes
| Status | Meaning |
|---|---|
| 400 | A parameter is missing or invalid — the message says which. |
| 401 | No API key, or the key is invalid or revoked. |
| 404 | Nothing found (geocoding, reverse geocoding) or no route between the points. |
| 429 | Either your monthly usage units are used up (calls resume when the period resets, or upgrade), or you hit your plan's rate limit (retry after the Retry-After header). |
| 503 | The service is busy or temporarily unavailable — retry after the Retry-After header. |
Server errors (5xx) are never counted toward your usage units.
Quota headers
Billable responses carry your balance of usage units, so you can track it without calling anything extra. Browsers can read them too (they're exposed via CORS).
| Header | Meaning |
|---|---|
| X-Orvia-Quota-Limit | Usage units included in your plan this period. |
| X-Orvia-Quota-Remaining | Usage units left this period. |
| X-Orvia-Quota-Reset | When the period resets (ISO 8601). |
| Server-Timing | Where the time went: queue, db, map, total (ms). |
Usage, rate and data limits
Three separate limits, each set by your plan (see Compare plans): monthly usage units (what you're billed for — 429 when used up, until the period resets), the rate limit (calls per minute — 429 with Retry-After), and data limits (Location Data collections and stored features — 403 when full).
Priority by plan
Map work is processed in plan order when the service is busy: Enterprise, Business, Startup, then Growth. A request that waits longer than 30 seconds is answered with 503 instead of running late.