Get started
Fetch data

Errors and retries

Errors and retries

Every failed call rejects with a class of the MountayaError family. The client retries what is worth retrying before it gives up.

Catch an error

import { isMountayaApiError, MountayaBillingError } from "@mountaya/client";

try {
  await mountaya.studio.itineraries.getItinerary({ itinerary_id: itineraryId });
} catch (error) {
  if (error instanceof MountayaBillingError) {
    // 402: your organization's agreement does not cover this call.
    showAgreementNotice(error);
  } else if (isMountayaApiError(error)) {
    console.error(error.status, error.code, error.errors[0]?.message, error.requestId);
  } else {
    throw error;
  }
}

isMountayaApiError narrows to a failure the API answered, with its status, code, errors and requestId. A timeout or a dropped connection is a MountayaConnectionError instead, and carries none of them.

Pick the class for the status

StatusClassMeans
400MountayaBadRequestErrorThe request is invalid
401MountayaAuthenticationErrorThe key is unknown, or the token expired or names no member
402MountayaBillingErrorYour agreement does not cover the call
403MountayaForbiddenErrorA scope, a domain, or a role is missing
404MountayaNotFoundErrorNo such resource for this credential
409MountayaConflictErrorA conflict, such as a lock
412MountayaPreconditionFailedErrorThe resource changed since you read it
429MountayaRateLimitErrorA limit is spent (wait retryAfter seconds), or a ceiling is full (LIMIT_REACHED)
5xxMountayaServerErrorThe API failed

A 402 is fixed in your agreement or billing settings, not in code. Its message says which.

Retries

Retries are on by default: two retries with backoff, on 429, 502, 503, 504 and network failures. A Retry-After replaces the backoff. Writes are retried safely, because each one carries an idempotency key.

A co-pilot run's stream keeps reopening on a 503 for up to two minutes before it reports the error.

const mountaya = new Mountaya({
  credential: { publishableKey, sessionToken },
  retry: { maxRetries: 3, baseDelayMs: 500, maxDelayMs: 30_000, maxWaitMs: 120_000 },
});

// A search box that re-queries on every keystroke wants no retries.
await mountaya.studio.itineraries.getItineraries({ query: { limit: 5 } }, { retry: { maxRetries: 0 } });

Timeouts

Each attempt waits 30 seconds for a response by default. Set timeoutMs on the client, or on one call:

await mountaya.studio.itineraries.getItinerary(
  { itinerary_id: itineraryId },
  { timeoutMs: 5_000 },
);

Watch every answer

onResponse hears every answer, successes included: the operation, the status, the request id, and the rate-limit state.

const observed = new Mountaya({
  credential: { publishableKey, sessionToken },
  onResponse: ({ operationId, rateLimit, requestId, status }) => {
    const minute = rateLimit?.policies.find(({ name }) => name === "minute");
    if (minute?.remaining === 0) {
      console.warn(`${operationId} (${status}, request ${requestId}) spent the minute`);
    }
  },
});

Quote the requestId to support: it is the id the API recorded the request under.

Next steps

Last updated