Error codes

Every error is JSON with a stable code and a message you can show. The shapes are on the conventions page; this page lists every code, what it means and which calls give it. A refused call costs no credits.

Rate and credit limits answer 429 with Retry-After; limit names which limit was reached.

400

Code	What it means	From
`invalid_coordinates`	A point outside lon −180…180, lat −90…90	Analyse a route you already have, Weather along a route at arrival time, Elevation profile of a line, Clean a GPX file, Exits along a route, Route card to print, Go windows: which day and start time, Slope at the path (experimental), Route brief, Places along a route, Pace plan for a course, Simplify a GPX file or line
`invalid_gpx`	gpx is not a string or has no <gpx> element	Analyse a route you already have, Weather along a route at arrival time, Elevation profile of a line, Clean a GPX file, Exits along a route, Route card to print, Go windows: which day and start time, Slope at the path (experimental), Route brief, Places along a route, Pace plan for a course, Simplify a GPX file or line
`invalid_request`	Not JSON, not an object, unknown field, both or neither of gpx/geometry, a bad profile or elevation, a geometry that is not a line	Analyse a route you already have, Round trips from a start point, Weather along a route at arrival time, Elevation profile of a line, Clean a GPX file, Exits along a route, Route card to print, Go windows: which day and start time, Slope at the path (experimental), Route brief, Places along a route, Pace plan for a course, Route through waypoints, Simplify a GPX file or line, keys and projects, downloads
`pace_required`	run or bike without min_per_km or kmh	Weather along a route at arrival time, Go windows: which day and start time

401

Code	What it means	From
`credential_invalid`	Unknown, revoked or rotated API key	any call, keys and projects
`key_required`	a bulk job (/v1/jobs) without a secret key; a publishable key gets 403 scope_denied	any call
`unauthorized`	No token or key, or an expired JWT. The console refreshes the session once, then asks the user to sign in	keys and projects

403

Code	What it means	From
`download_link_expired`	a link past exp	downloads
`download_link_invalid`	a link with a wrong signature, or for another file	downloads
`origin_not_allowed`	a publishable key (ts_pub_) from an origin outside its allowlist, or without an origin	any call
`scope_denied`	An API key used on an owner endpoint (keys cannot manage projects)	keys and projects, downloads

404

Code	What it means	From
`not_found`	Unknown project or key, or one owned by someone else	keys and projects, downloads

405

Code	What it means	From
`method_not_allowed`	Any method but POST; the answer carries Allow: POST	Analyse a route you already have, Round trips from a start point, Weather along a route at arrival time, Elevation profile of a line, Clean a GPX file, Exits along a route, Route card to print, Go windows: which day and start time, Slope at the path (experimental), Route brief, Places along a route, Pace plan for a course, Route through waypoints, Simplify a GPX file or line

409

Code	What it means	From
`capability_unavailable`	bike while the served routing tiles carry no verified one-ways or turn restrictions (as the Planner's loops)	Round trips from a start point
`key_limit`	Plan limit reached; limit names it	keys and projects
`project_closed`	Writing to a closed project	keys and projects
`project_limit`	Plan limit reached; limit names it	keys and projects

413

Code	What it means	From
`body_too_large`	Body over 1 MB (answered as JSON with CORS, like every refusal)	Analyse a route you already have, Weather along a route at arrival time, Elevation profile of a line, Clean a GPX file, Exits along a route, Route card to print, Go windows: which day and start time, Slope at the path (experimental), Route brief, Places along a route, Pace plan for a course, Route through waypoints, Simplify a GPX file or line
`too_many_points`	More than 5,000 points	Analyse a route you already have, Weather along a route at arrival time, Elevation profile of a line, Clean a GPX file, Exits along a route, Route card to print, Go windows: which day and start time, Slope at the path (experimental), Route brief, Places along a route, Pace plan for a course, Simplify a GPX file or line

422

Code	What it means	From
`bad_straight_leg`	A straight leg the router cannot draw	Route through waypoints
`beyond_forecast`	More than six hours ago, or more than 16 days ahead	Weather along a route at arrival time, Route card to print, Go windows: which day and start time, Route brief
`budget_exhausted`	The job's 25 s / 12 M-node budget ran out (the job is receipted budget:*)	Analyse a route you already have, Weather along a route at arrival time, Elevation profile of a line, Exits along a route, Route card to print, Slope at the path (experimental), Places along a route, Pace plan for a course, Route through waypoints
`budget_too_small`	max_points below the ends of every segment and every stop	Clean a GPX file, Simplify a GPX file or line
`corridor_too_large`	A window's corridor is too dense to load; send the line in pieces	Analyse a route you already have, Round trips from a start point, Exits along a route, Route card to print, Route through waypoints
`departure_in_past`	More than six hours ago, or more than 16 days ahead	Weather along a route at arrival time, Route card to print, Go windows: which day and start time, Route brief
`disconnected`	No path joins two waypoints under the settings, or none within the area searched; the message names the leg, and the error carries cap_alternative when a harder grade would join them	Route through waypoints
`invalid_coordinates`	Simplify: GPX points whose coordinates cannot be read (clean first)	Clean a GPX file, Simplify a GPX file or line
`leg_too_long`	A leg over 60 km in a straight line: add waypoints	Route through waypoints
`legs_mismatch`	leg_seconds does not have one value per leg	Route card to print
`no_line`	No part of two or more points	Analyse a route you already have, Weather along a route at arrival time, Elevation profile of a line, Clean a GPX file, Exits along a route, Route card to print, Go windows: which day and start time, Slope at the path (experimental), Route brief, Places along a route, Pace plan for a course, Simplify a GPX file or line
`no_loop`	No loop: the start is not near a path the settings may use, or none was found. The body also carries status: none, reason, request and search	Round trips from a start point
`no_path_in_corridor`	No path joins two waypoints under the settings, or none within the area searched; the message names the leg, and the error carries cap_alternative when a harder grade would join them	Route through waypoints
`no_path_under_settings`	No path joins two waypoints under the settings, or none within the area searched; the message names the leg, and the error carries cap_alternative when a harder grade would join them	Route through waypoints
`output_too_large`	The answer would exceed 5 MB (never truncated)	Analyse a route you already have
`several_parts`	More than one part (track segment, line)	Weather along a route at arrival time, Exits along a route, Route card to print, Go windows: which day and start time, Route brief, Pace plan for a course
`snap_failed`	A waypoint is farther than the snap radius from any path the settings allow	Route through waypoints
`too_large`	The line would read more than 120 terrain tiles (a guard; a 120 km line reads a few dozen)	Slope at the path (experimental)
`too_long`	More than 300 km	Analyse a route you already have, Round trips from a start point, Weather along a route at arrival time, Elevation profile of a line, Exits along a route, Route card to print, Go windows: which day and start time, Slope at the path (experimental), Route brief, Places along a route, Pace plan for a course
`too_short`	Under 0.2 km	Pace plan for a course

429

Code	What it means	From
`bbox_daily_ceiling`limit: "bbox_daily"	a keyed project past its daily bbox calls (/pois/v1/bbox, /trails/v1/bbox, /trails/v1/restrictions): three times its plan's daily average credits (Free 3,000, Starter 15,000, Pro 60,000, Business 250,000). Retry-After until 00:00 UTC	any call
`concurrency_limit`limit: "concurrency"	a heavy request (round trips, route analysis, route weather, route brief, route exits, route card) while the project (or the address, without a key) already has its limit running. Retry-After: 2	any call
`download_cap`limit: "monthly_bytes"	the bytes would pass the plan's monthly cap	downloads
`keyless_daily_credits_exhausted`limit: "keyless_daily"	a call without a key past 500 credits today from its address	any call
`monthly_credits_exhausted`	Allowance used up; Retry-After = seconds to period.end	any call, keys and projects, downloads
`rate_limit`limit: "burst", "publishable_visitor", "operation"	Too many requests per second; limit says which: burst (your key), ip (your address without a key), publishable_visitor (one visitor on a browser key) or operation (a per-operation limit). Wait Retry-After.	any call, keys and projects

502

Code	What it means	From
`forecast_failed`	The forecast answered in error or in an unexpected shape	Weather along a route at arrival time

503

Code	What it means	From
`accounting_unavailable`	A key was sent but the API cannot check keys just now; calls without a key go on. Retry after Retry-After.	any call, keys and projects
`forecast_unavailable`	The forecast has nothing current; Retry-After	Weather along a route at arrival time, Go windows: which day and start time
`overloaded`	The worker's heavy-job queue is full; Retry-After: 5	Analyse a route you already have, Round trips from a start point, Weather along a route at arrival time, Clean a GPX file, Exits along a route, Route card to print, Route brief, Route through waypoints, Simplify a GPX file or line
`places_unavailable`	The places index did not answer; retry	Places along a route
`terrain_unavailable`	The terrain model did not answer, and the line carries too few heights of its own; try again	Elevation profile of a line
`tiles_unavailable`	Routing tiles could not be read	Analyse a route you already have, Round trips from a start point, Exits along a route, Route card to print