Errors
Every Mountaya API reports a failure the same way: an errors array whose entries carry a message for people and an extensions.code for your code. Branch on the code, never on the message.
Every answer, a refusal included, carries an X-Request-Id. Log it beside the error and quote it when you contact support.
A Data API query that runs answers 200 OK, even when a field fails. Check errors on every response: a partial result carries both data and errors. The input field at fault is in extensions.path.
Retry only what time can fix: a 429 not coded LIMIT_REACHED, a 409 coded IDEMPOTENCY_KEY_IN_USE, and a 5xx. Wait Retry-After when the answer carries it, and back off with jitter otherwise. Every other 4xx describes your request, so the same request fails the same way.
Retry a write with the same Idempotency-Key, so it never runs twice. The TypeScript client does all of this for you.
A 429 coded LIMIT_REACHED means a ceiling is full, such as your seats or your published itineraries. It carries no Retry-After, because waiting does not lift it. Free a place, such as unpublishing an itinerary, or change the agreement, then send the request again.
A 402 means your organization does not hold the product the request needs. The Data API and the MCP server are self-serve: an owner or admin adds a card. Every other product comes with an agreement: talk to us.
A 409 Conflict names what the write collided with at extensions.metadata: a name already taken, an address already invited, or a part of an itinerary another member is editing. Only the Map Studio API sends one.
Editing an itinerary or a zone locks the part being changed. A write to a part someone else holds is refused with 409, and extensions.metadata.holder.id names that member. Wait for them to finish, or pick another part.
A request that is wrong in several ways is answered for the first check it fails, and that one alone. Fix what the answer names and send it again. The credential is checked before the body, so a bad key is a 401 however malformed the body is.