Errors & Retries - Cesto

Error hierarchy

Everything the SDK throws extends CestoError. Server responses become typed APIError subclasses; transport problems become connection errors. All classes are exposed on the Cesto client for instanceof checks.

import { Cesto } from '@cesto/sdk';

try {
  await cesto.products.get({ slug: 'missing-slug' });
} catch (err) {
  if (err instanceof Cesto.NotFoundError) {
    // 404
  } else if (err instanceof Cesto.AuthenticationError) {
    // 401, invalid / missing / revoked key
  } else if (err instanceof Cesto.RateLimitError) {
    // 429, err.retryAfter (ms)
  } else if (err instanceof Cesto.APIConnectionError) {
    // network failure or timeout
  } else {
    throw err;
  }
}

Class	When
`BadRequestError`	400
`AuthenticationError`	401, invalid / missing / revoked key
`PermissionDeniedError`	403
`NotFoundError`	404
`ConflictError`	409
`UnprocessableEntityError`	422
`RateLimitError`	429, carries `retryAfter` (ms)
`InternalServerError`	5xx
`APIConnectionError`	network failure
`APIConnectionTimeoutError`	request exceeded `timeout`
`APIUserAbortError`	your `AbortSignal` fired

Every APIError carries status, code, requestId, and details from the API, useful when reporting an issue.

Automatic retries

Transient failures (408, 429, 5xx, connection errors, and timeouts) are retried automatically with exponential backoff and jitter, honoring the Retry-After header. Tune with maxRetries (default 2), or disable per request with { maxRetries: 0 }.

A handful of non-idempotent methods are never retried automatically, regardless of maxRetries: positions.submit (a submit that timed out client-side may still have been accepted — poll getExecution instead of re-sending), the consent-path open.start / close.start / rebalance.start, and bridge.submitBurn / bridge.initiate.

Timeouts & cancellation

Each request times out after timeout ms (default 60s), throwing APIConnectionTimeoutError. Pass an AbortSignal to cancel a request yourself:

const controller = new AbortController();
const promise = cesto.products.list({}, { signal: controller.signal });
controller.abort(); // → APIUserAbortError