Errors

A 2xx status means the request succeeded. A 4xx means the request was refused and the body says why; a 5xx means something went wrong on Waygo's side (rare; retry later, and tell us if it persists).

Refusals carry a JSON body with an error token: a stable, machine-readable word your code can branch on. Some tokens come with extra fields that explain the refusal (blockers, reason, next_available_at).

A refusal

{ "error": "map_not_ready", "blockers": ["base_map_not_published"] }

A refusal with a reason

{ "error": "section_not_editable", "section": "anchor", "reason": "staff_only" }

Status codes

Name
400
Description
The request cannot be processed as sent (for example an image upload to a column that is not an image column).
Name
403
Description
The key or user lacks the scope, or the action is not available on this map right now (capability_denied, section_not_editable, kiosk_setup_token_invalid).
Name
404
Description
No such map, catalog, row, kiosk or placement, or a map that is not public (map_not_available).
Name
409
Description
The action conflicts with the map's state: map_not_ready, license_inactive, publish_in_progress, level_without_walking_paths, floor_plan_status_conflict.
Name
422
Description
The body did not validate: a missing field, a bad value, a rule broken (link_invalid, kiosk_position_invalid, bulk_row_cap_exceeded, floor_plan_invalid_file).
Name
429
Description
publish_allowance_exceeded: today's publishes are used up or the interval has not passed. next_available_at and the Retry-After header say when to try again.

Validation errors

When a body fails validation before reaching Waygo's logic, the response is the standard FastAPI shape: a detail list naming each offending field.

422

{
  "detail": [
    { "loc": ["body", "name"], "msg": "Field required", "type": "missing" }
  ]
}

Tokens you will meet

Token	Status	Where
`map_not_available`	404	Loading a draft, offline or expired map without a preview token.
`map_not_ready`	409	Going live, or minting a preview, before Waygo has built the map. `blockers` lists what is missing.
`license_inactive`	409	Going live or publishing after the license ended.
`publish_in_progress`	409	Publishing while a run is in flight.
`publish_allowance_exceeded`	429	Publishing beyond the allowance.
`section_not_editable`	403	A settings section your account may not change.
`capability_denied`	403	An action the map's state does not allow; `capability` and `reason` say which and why.
`floor_plan_invalid_file`	422	A floor plan file of the wrong type or size.
`floor_plan_status_conflict`	409	Deleting a floor plan Waygo has started building.
`kiosk_not_found`	404	No such kiosk.
`kiosk_not_placed`	409	Directions from a kiosk that has no position yet.
`kiosk_setup_token_invalid`	403	A setup link that was already used, superseded or expired.
`kiosk_position_invalid`	422	A level the map lacks, or bad coordinates.
`level_without_walking_paths`	409	The level has no walking paths; directions cannot start there.
`placement_not_on_map`	404	Building a link to a placement that is not on this map.
`link_invalid`	422	A link request that contradicts itself (start equals end, an unknown level).
`bulk_criteria_invalid`	422	A bulk-links rule with an unknown column or operator.
`bulk_row_cap_exceeded`	422	More than 5,000 links in one bulk run.