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.

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
│   └── ServiceUnavailableError    SERVICE_UNAVAILABLE         true
├── RequestError                   REQUEST_FAILED              false
│   ├── ValidationError            VALIDATION_FAILED           false
│   │   ├── StaleQuoteError            STALE_QUOTE
│   │   └── PolicyScopeMismatchError   POLICY_SCOPE_MISMATCH
│   ├── ResourceNotFoundError      RESOURCE_NOT_FOUND          false
│   ├── NotImplementedError        NOT_IMPLEMENTED             false
│   ├── AlreadyExistsError         ALREADY_EXISTS              false
│   ├── 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
└── InternalServerError            INTERNAL_SERVER_ERROR       false

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.
	}
}

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

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.

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, or market-overview RPC errors.
• PolyesterErrorOptions: { cause?: unknown; detail?: PolyesterErrorDetail } accepted by every constructor.
• RateLimitErrorOptions: adds retryAfterMs?: number and rateLimit?: RateLimitDetail.
• RateLimitDetail: structured quota state with exact decimal-string counter values.
• OrderErrorDetail: an Orders rejection code, violations, and optional rateLimit state.

Related Topics