Get started

API conventions

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.

Response
{
  "errors": [
    {
      "message": "Activity is not recognized",
      "path": ["request", "body", "activity_id"],
      "extensions": { "code": "VALIDATION_FAILED" }
    }
  ]
}
FieldWhat it holds
messageA sentence for a person, translated by Accept-Language. Never parse it.
pathThe field the entry is about, when there is one.
extensions.codeOne of the codes below. Always present.

Every answer, a refusal included, carries an X-Request-Id. Log it beside the error and quote it when you contact support.

Error codes

CodeStatusWhat to do
BAD_REQUEST400Fix the request: unreadable body, wrong content type, bad parameter.
VALIDATION_FAILED400Fix the one field named in path.
UNAUTHORIZED401Send a valid credential. See authentication.
PAYMENT_REQUIRED402Get the product. A retry does not help. See payment errors.
FORBIDDEN403Stop. The credential is valid but not permitted.
LIMIT_REACHED429A ceiling is full. Free a place or change the agreement. See ceilings.
NOT_FOUND404No resource with that id is visible to this credential.
METHOD_NOT_ALLOWED405Use a method the Allow header names.
CONFLICT409Read extensions.metadata and resolve it. See conflicts.
AI_PROVIDER_NOT_CONFIGURED409Configure the organization's AI provider, then start the run again.
IDEMPOTENCY_KEY_IN_USE409The first request with this key still runs. Wait Retry-After, then resend.
IDEMPOTENCY_ANSWER_UNAVAILABLE409The write was made, but its answer is gone. Read the resource; do not resend.
REDELIVERY_IN_PROGRESS409Wait for the redelivery already running to this endpoint.
SECRET_ROTATION_IN_OVERLAP409Wait for the overlap to end, or rotate with none.
PRECONDITION_FAILED412The resource changed since you read it. See conditional writes.
PAYLOAD_TOO_LARGE413Send a smaller body. As a Data API entry under 200, at ["input"], it is an itinerary of more than 500,000 positions, which itinerary and exportItinerary refuse whatever the body.
TOO_MANY_REQUESTS429Wait Retry-After, then retry. See rate limits.
INTERNAL_ERROR500Retry once, then report it with the request id.
NOT_IMPLEMENTED501Declared, not yet served.
BAD_GATEWAY502Declared, not sent by any API.
SERVICE_UNAVAILABLE503Wait Retry-After, or back off, then retry.
GATEWAY_TIMEOUT504Retry once, then ask for less. See timeouts.

Data API errors arrive under 200

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.

Response
{
  "errors": [
    {
      "message": "Must have at least 2 waypoints",
      "path": ["directions"],
      "locations": [{ "line": 1, "column": 46 }],
      "extensions": {
        "code": "VALIDATION_FAILED",
        "path": ["input", "waypoints"]
      }
    }
  ],
  "data": null
}

Retry or fix

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.

Ceilings

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.

Response
{
  "errors": [{ "message": "The organization has no seat left", "extensions": { "code": "LIMIT_REACHED" } }],
  "extensions": { "metadata": { "limit": "seats", "allowed": 10, "used": 10 } }
}

Payment required

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.

Conflicts

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.

A collaborator holds the lock

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.

Which check fails first

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.

Next steps

Last updated