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. Errors mapped from a failed response carry its HTTP status (for a Connect error without a raw HTTP status, the Connect protocol's status for its code), including realtime token request failures; status is undefined when no response arrived. For usage patterns, see the Error handling guide.

Unknown protobuf enum values in read responses do not raise ValidationError. The affected field decodes as "unspecified", preserving the rest of the response when a newer server adds an enum member that this SDK version does not recognize.

Hierarchy

PolyesterError                     code                        retryable
├── TransientError                 TRANSIENT_FAILURE           true
│   ├── NetworkError               NETWORK_ERROR               true
│   ├── TimeoutError               TIMEOUT                     true
│   ├── RateLimitError             RATE_LIMITED                true
│   ├── TimestampSkewError         TIMESTAMP_SKEW              true
│   └── ServiceUnavailableError    SERVICE_UNAVAILABLE         true
├── RequestError                   REQUEST_FAILED              false
│   ├── ValidationError            VALIDATION_FAILED           false
│   │   ├── StaleQuoteError            STALE_QUOTE
│   │   ├── WithdrawDeadlineExpiredError WITHDRAW_DEADLINE_EXPIRED
│   │   └── PolicyScopeMismatchError   POLICY_SCOPE_MISMATCH
│   ├── ResourceNotFoundError      RESOURCE_NOT_FOUND          false
│   ├── NotImplementedError        NOT_IMPLEMENTED             false
│   ├── AlreadyExistsError         ALREADY_EXISTS              false
│   │   └── UserOperationAlreadyKnownError USER_OPERATION_ALREADY_KNOWN
│   ├── PermissionError            PERMISSION_DENIED           false
│   ├── AuthenticationError        UNAUTHENTICATED             false
│   ├── PreconditionFailedError    PRECONDITION_FAILED         false
│   │   ├── RevisionConflictError      REVISION_CONFLICT
│   │   ├── PolicyInUseError           POLICY_IN_USE
│   │   ├── PolicyLockedError          POLICY_LOCKED
│   │   ├── SubaccountChallengeInvalidError SUBACCOUNT_CHALLENGE_INVALID
│   │   └── MfaLastFactorRequiredError MFA_LAST_FACTOR_REQUIRED
│   ├── ConfigurationError         INVALID_CONFIGURATION       false
│   ├── MfaRequiredError           MFA_REQUIRED                false
│   │   ├── MfaEnrollmentRequiredError     MFA_ENROLLMENT_REQUIRED
│   │   ├── StepUpRequiredError            STEP_UP_REQUIRED
│   │   └── SessionElevationRequiredError  SESSION_ELEVATION_REQUIRED
│   ├── MfaVerificationError       MFA_VERIFICATION_FAILED     false
│   ├── UserOperationSendTimeoutError USER_OPERATION_SEND_TIMEOUT false
│   ├── OutcomeUnknownError        OUTCOME_UNKNOWN             false
│   └── UserOperationNotExecutedError USER_OPERATION_NOT_EXECUTED false
├── InternalServerError            INTERNAL_SERVER_ERROR       false
└── RealtimeError                  REALTIME_ERROR              varies

Class notes

Catalog errors

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

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

Structured backend details

Typed RPC errors expose the first recognized backend rejection as PolyesterError.detail. The value is undefined when the backend provided no recognized detail. It survives SDK error wrapping, so inspect it directly instead of walking an error's cause chain.

import { PolyesterError } from "@polyester/sdk";

try {
	await client.orders.cancelAll({ symbolIds: [symbolId] });
} catch (error) {
	if (
		error instanceof PolyesterError &&
		error.detail?.service === "orders" &&
		error.detail.code === "CANCEL_REQUEST_EXPIRED"
	) {
		// The cancellation replay window elapsed; use a fresh requestId.
	}
}

SDK transports load the detail decoders before mapping an error. Outside SDK transports, for example when mapping a raw ConnectError from your own client with toPolyesterError, call await loadErrorDetailDecoders(error) first, or loadErrorDetailDecoders() once to preload every decoder. Without them the error still maps, but detail is undefined.

import { loadErrorDetailDecoders, toPolyesterError } from "@polyester/sdk";

try {
	await rawClient.someMethod(request);
} catch (error) {
	await loadErrorDetailDecoders(error);
	throw toPolyesterError(error);
}

For market-order stale quotes, use error instanceof StaleQuoteError (imported from @polyester/sdk) or inspect an orders detail with code STALE_QUOTE.

API-key refusals carry an auth detail.code naming the reason: AUTH_SIGNATURE_INVALID, AUTH_TIMESTAMP_SKEW, AUTH_MISSING_HEADERS, AUTH_KEY_EXPIRED, AUTH_KEY_DISABLED, AUTH_IP_NOT_ALLOWED, or AUTH_API_KEY_NOT_ACCEPTED. AUTH_TIMESTAMP_SKEW maps to the retryable TimestampSkewError. AUTH_TEMPORARILY_UNAVAILABLE maps to a retryable ServiceUnavailableError, and AUTH_SOCIAL_ACCOUNT_ALREADY_LINKED to AlreadyExistsError.

Orders details with ORDER_CREATE_OUTCOME_UNKNOWN, ORDER_CANCEL_OUTCOME_UNKNOWN, ORDER_MODIFY_OUTCOME_UNKNOWN, TRIGGER_CREATE_OUTCOME_UNKNOWN, or TRIGGER_CONTROL_OUTCOME_UNKNOWN throw OutcomeUnknownError. A deadline without one of these details is a retryable TimeoutError.

For transfer failures, detail.service is "withdraw" or "internal_transfer", with the service's stable backend error code. Transfer rate-limit details map to RateLimitError; temporary withdrawal or internal-transfer dependency failures map to ServiceUnavailableError.

Daily reward claim failures use detail.service === "claims". Claims rate-limit details map to RateLimitError; SERVICE_UNAVAILABLE and CLAIM_TEMPORARILY_UNAVAILABLE map to ServiceUnavailableError. SOCIAL_VERIFICATION_REQUIRED is a non-retryable PreconditionFailedError: the user must verify an X or Discord account before claiming. CLAIM_PAYOUT_UNAVAILABLE means the campaign's payouts are paused; it also appears as a daily claim's payoutDelayReason. When a claim names a payout subaccount, SUBACCOUNT_NOT_FOUND (Connect not_found, HTTP 404) maps to ResourceNotFoundError and is also returned for subaccounts the authenticated root account does not own, including shared ones. SUBACCOUNT_INACTIVE (Connect failed_precondition, HTTP 400) maps to PreconditionFailedError for an owned subaccount that is disabled. See client.claims.

Order details have service: "orders" plus the existing OrderErrorDetail fields. Rejected batch-create, batch-replace, and batch-cancel result items continue to expose that optional error field.

OrderErrorCode includes policy-specific rejections such as POLICY_MAX_OPEN_ORDERS, SUBACCOUNT_READ_FORBIDDEN, POLICY_SPOT_READ_DENY, API_KEY_SPOT_READ_DENY, and CANCEL_REQUEST_EXPIRED.

Rate-limit details

RateLimitError.rateLimit preserves quota values that may exceed JavaScript's safe integer range:

import type {
	RateLimitFailureReason,
	RateLimitPolicyClass,
	RateLimitRefillModel,
	RateLimitScope,
} from "@polyester/sdk";

interface RateLimitDetail {
	reason: RateLimitFailureReason;
	operationId: string;
	policyClass: RateLimitPolicyClass;
	scope: RateLimitScope;
	refillModel: RateLimitRefillModel;
	limit?: string;
	remaining?: string;
	retryAfterMs?: string;
	policyVersion?: string;
}

retryAfterMs on the error is a number only when conversion is safe or a response header supplies one. Use the string fields in rateLimit when exact quota data matters.

client.tradingRateLimits is the discovery API for those trading pools: public catalog via getConfig, effective account limits via getTradingLimits. See Trading rate limits.

Helper functions

Types

• PolyesterErrorCode: union of every code string above.
• PolyesterErrorDetail: discriminated backend rejection detail for auth, profile, orders, withdrawal, internal transfer, ledger, market-overview, or claims RPC errors.
• PolyesterErrorOptions: { cause?: unknown; detail?: PolyesterErrorDetail; status?: number } accepted by every constructor.
• RateLimitErrorOptions: adds retryAfterMs?: number and rateLimit?: RateLimitDetail.
• RealtimeErrorOptions: adds realtimeCode?: number and retryable?: boolean.
• RateLimitDetail: structured quota state with exact decimal-string counter values.
• OrderErrorDetail: an Orders rejection code, violations, and optional rateLimit state.

Related Topics