Errors

Every error the SDK raises extends PolyesterError, with a stable machine-readable code and a retryable flag. RPC failures keep the original ConnectRPC error as cause. For usage patterns, see the Error handling guide.

Hierarchy

PolyesterError                     code                        retryable
├── TransientError                 TRANSIENT_FAILURE           true
│   ├── NetworkError               NETWORK_ERROR               true
│   ├── TimeoutError               TIMEOUT                     true
│   ├── RateLimitError             RATE_LIMITED                true
│   └── ServiceUnavailableError    SERVICE_UNAVAILABLE         true
├── RequestError                   REQUEST_FAILED              false
│   ├── ValidationError            VALIDATION_FAILED           false
│   ├── ResourceNotFoundError      RESOURCE_NOT_FOUND          false
│   ├── AlreadyExistsError         ALREADY_EXISTS              false
│   ├── PermissionError            PERMISSION_DENIED           false
│   ├── AuthenticationError        UNAUTHENTICATED             false
│   ├── PreconditionFailedError    PRECONDITION_FAILED         false
│   ├── ConfigurationError         INVALID_CONFIGURATION       false
│   └── MfaRequiredError           MFA_REQUIRED                false
│       ├── MfaEnrollmentRequiredError     MFA_ENROLLMENT_REQUIRED
│       ├── StepUpRequiredError            STEP_UP_REQUIRED
│       └── SessionElevationRequiredError  SESSION_ELEVATION_REQUIRED
└── InternalServerError            INTERNAL_SERVER_ERROR       false

Class notes

Class	When
`TransientError`	The request may not have reached the backend, or it was temporarily unable to serve it. Safe to retry — reuse the same `requestId` / `clientOrderId` so the backend dedupes.
`NetworkError`	The request could not be sent or the connection failed mid-flight.
`TimeoutError`	No response before the deadline.
`RateLimitError`	Backend rate limiting. Carries `retryAfterMs?: number` when the backend suggests a wait.
`ServiceUnavailableError`	Backend overloaded or restarting (502/503/504).
`RequestError`	The request itself was rejected — an identical retry fails identically.
`ValidationError`	Input failed validation (client- or server-side).
`ResourceNotFoundError`	Resource missing or not visible to the caller.
`AlreadyExistsError`	Duplicate — e.g. a reused `clientOrderId`.
`PermissionError`	Authenticated but not allowed.
`AuthenticationError`	Missing/expired/invalid credentials.
`PreconditionFailedError`	System state forbids it (e.g. insufficient balance).
`ConfigurationError`	The SDK itself is misconfigured (bad environment, missing credentials).
`MfaRequiredError`	Umbrella for the three MFA flows below.
`MfaEnrollmentRequiredError`	User must enroll an MFA factor first.
`StepUpRequiredError`	Needs a fresh one-use proof — retry with `options.stepUpToken`.
`SessionElevationRequiredError`	Needs a recently MFA-elevated session.
`InternalServerError`	Backend failure or malformed response. Not auto-retryable — mutations may have partially applied.

Catalog errors

Raised by catalog reads and decimal conversion; they plug into the same tree under RequestError / ValidationError:

Class	Code	When
`CatalogLookupError`	`CATALOG_LOOKUP_MISS`	`require*` lookup for an unknown pair/asset/chain.
`CatalogNotReadyError`	`CATALOG_NOT_READY`	Direct catalog read before a snapshot exists.
`CatalogConversionError`	`CATALOG_CONVERSION_INVALID`	Non-decimal input or excess precision.
`CatalogValidationFailedError`	`CATALOG_VALIDATION_FAILED`	Order input violates pair constraints (tick/step/min).

The catalog classes are exported from @polyester/sdk/catalogs; everything else on this page comes from the root export.

Helper functions

Function	Purpose
`isAbortError(err)`	Caller-initiated `AbortSignal` cancellations — deliberately outside the `PolyesterError` tree.
`isRetryableError(err)`	`true` for `TransientError` subclasses.
`isResourceNotFoundError(err)`	Convenience type guard.
`isFreshStepUpRequiredError(err)` / `isSessionElevationRequiredError(err)` / `isMfaEnrollmentRequiredError(err)`	MFA flow guards for unknown error values.
`errorFromHttpStatus(status, message, options?)`	Map a plain HTTP status onto the tree (401→`AuthenticationError`, 429→`RateLimitError`, …).
`toPolyesterError(err)` / `connectErrorToPolyesterError(err)`	Normalize arbitrary/Connect errors into the tree.
`createErrorMappingInterceptor()`	The interceptor the SDK installs so every RPC failure is typed (exported for custom transports).
`normalizeErrorMessage(message)`	Strip Connect's `[code]` prefixes from messages.
`formatConnectError(err, fallback)`	Human-readable message from any error.

Types

PolyesterErrorCode — union of every code string above.
PolyesterErrorOptions — { cause?: unknown } accepted by every constructor.
RateLimitErrorOptions — adds retryAfterMs?: number.