Errors and retries

Every failure @endstate-sdk/core raises is a typed error carrying the information support needs. Retry behaviour is not guesswork either: it is derived from the API spec at build time, so a call is retried only when repeating it is safe.

Branch on the code

import { isEndstateError, isEndstateApiError } from "@endstate-sdk/core/errors";

try {
  await endstate.chips.pair({ unit_id, chip_id, e, c });
} catch (error) {
  if (isEndstateApiError(error)) {
    error.code; // "chip.already_scanned"
    error.status; // 409
    error.requestId; // quote this to support
    error.docUrl; // link to the error's documentation
    error.retryAdvice; // "never" | "retry" | "wait_and_retry" | "poll_resource"
    error.details; // validation failures, when the code carries them
  }
  if (isEndstateError(error)) {
    error.attempts; // greater than 1 means the SDK retried
  }
}

Branch on error.code, never on message or the HTTP status. Several codes share one status. Codes are added over time, so treat an unrecognized one as a generic failure rather than throwing.

Narrow to specific codes with isEndstateError(error, ...codes):

if (isEndstateError(error, "chip.already_scanned", "chip.invalid_e_value")) {
  // The tap credential was spent or malformed - ask for a fresh tap.
}

The error types

Type	When
`EndstateApiError`	The API replied with an error envelope
`EndstateHttpError`	A non-2xx that carried no envelope
`EndstateNetworkError`	The request never completed
`EndstateTimeoutError`	Your `timeoutMs` or `maxElapsedMs` elapsed
`EndstateTerminalStateError`	A `waitUntil` helper found a settled failure
`EndstateConfigError`	A credential was missing or wrong-prefixed at startup
`ChipUrlError`	The input was not a tap URL

All extend EndstateError, which carries requestId, operationId, and attempts. Log requestId on every failure - it is the fastest way for support to find your request.

Which calls are retried

Retry eligibility comes from the spec, not from the method name. Every operation falls into one of three classes.

Class	Calls	Retried on
Read	Every `GET`	Network failure, timeout, `429`, `5xx`
Keyed	Creates that accept an `Idempotency-Key`	Network failure, timeout, `429`, `409 idempotency.in_progress`
Write	Updates and other mutations that accept no key	`429` only

Two consequences worth internalizing: A keyed write is never retried on a 5xx. The API clears its idempotency record on any non-2xx, so a same-key retry would execute a second time instead of replaying the first. The SDK will not do that for you. Writes are never repeated at all. units.update, collections.update, settings.update, settings.corsOrigins.replace, sessionTokens.revoke, and testHelpers.createTap accept no idempotency key, so the API cannot deduplicate them and a second send is a second write. Raising maxAttempts does not change this, and that is not a bug. The single exception is 429 rate_limit.exceeded, which the API refuses before any handler runs, so nothing was written.

Where the idempotency key comes from

For a keyed create, the SDK sends an Idempotency-Key on your behalf. Which key it sends determines whether a later run is safe, and error.safeToRetry tells you which case you are in.

// You supply the key - stable across runs. safeToRetry is true.
await endstate.units.create(body, { idempotencyKey: "jacket-0001" });

// The SDK generates one - stable across this call's retries only.
await endstate.units.create(body);

This matters when a call fails without an answer. EndstateNetworkError and EndstateTimeoutError - the two cases where you cannot know whether the write landed - carry safeToRetry and the idempotencyKey that was used. safeToRetry means “calling again recovers this same operation”. It is true for a read, and for a write whose key is stable across calls - one you supplied, or the one verify() derives from the tap. It is false when the SDK generated the key, because a fresh call would generate a different one and the API would treat it as a second write. Pass the key back to recover the original:

import {
  EndstateNetworkError,
  EndstateTimeoutError,
} from "@endstate-sdk/core/errors";

try {
  await endstate.units.create(body);
} catch (error) {
  const unresolved =
    error instanceof EndstateNetworkError ||
    error instanceof EndstateTimeoutError;

  if (unresolved && !error.safeToRetry && error.idempotencyKey) {
    // Same key, so this replays the original instead of creating a second unit.
    await endstate.units.create(body, { idempotencyKey: error.idempotencyKey });
  }
}

When the same logical create can be issued by a later run - a nightly sync, a job that may be replayed - supply your own key. The resource’s external_id or a job id is usually the right choice, so the second run replays the first response instead of creating a second resource.

Tuning it

Retries use equal-jitter exponential backoff and honour Retry-After. Configure per client or per call:

new EndstateClient({
  apiKey,
  timeoutMs: 15_000,
  retry: { maxAttempts: 5, baseDelayMs: 500 },
});

await endstate.units.get(id, { retry: false, signal: controller.signal });

DEFAULT_RETRY_POLICY is what applies when you set none - spread it to change one field without restating the rest:

import { DEFAULT_RETRY_POLICY } from "@endstate-sdk/core";

new EndstateClient({
  apiKey,
  retry: { ...DEFAULT_RETRY_POLICY, maxAttempts: 5 },
});

Observe what is happening with onRequest, onResponse, and onRetry:

new EndstateClient({
  apiKey,
  onRetry: ({ attempt, reason, delayMs }) => {
    logger.warn({ attempt, reason, delayMs }, "retrying");
  },
});

reason is one of network, timeout, rate_limited, server_error, or idempotency_in_progress.

Get started

Core SDK

Reader SDK

Branch on the code

The error types

Which calls are retried

Where the idempotency key comes from

Tuning it

​Branch on the code

​The error types

​Which calls are retried

​Where the idempotency key comes from

​Tuning it

Branch on the code

The error types

Which calls are retried

Where the idempotency key comes from

Tuning it