Errors

SDK errors implement error and match the sentinel errors.ErrPolyester via errors.Is. Use errors.As to unwrap concrete types.

Package: github.com/Fabric-Labs/polyester-sdk-go/errors.

For usage patterns see the Error handling guide.

Types

• *AuthError: Missing/invalid credentials; realtime HTTP errors include structured context
• *SessionRequiredError: The method accepts only a session token, not an API key
• *SubaccountOwnerRoleLockedError: A subaccount member call targets the owner
• *TimestampSkewError: Signature timestamp outside the server window; retryable
• *ValidationError: Bad SDK input (PostOnly, enums, shapes, precision), or a named-field refusal
• *TransportError: Network / timeout, usually retryable with backoff; Err (via Unwrap) holds the cause, such as context.Canceled or context.DeadlineExceeded
• *RateLimitError: Rate limited; optional RetryAfter *float64 and Detail
• *ServerError: Backend 5xx
• *APIError: Structured Connect/API error (Code, Metadata, ExistingOrderID)
• *ResponseContractError: Successful mutation response was incomplete or internally inconsistent
• *BatchReplaceWindowExpiredError: WaitBatchReplace outlived the 60-second status window
• *NotImplementedError: The server does not offer the operation
• *RouteNotFoundError: RPC not exposed on this host
• *RealtimeError: Realtime connect / decode failures
• *QueueOverflowError: Subscription queue full (fail-closed)

import sdkerrors "github.com/Fabric-Labs/polyester-sdk-go/errors"

_, err := client.Orders.Create(ctx, req, nil)
if err != nil {
    var rl *sdkerrors.RateLimitError
    if errors.As(err, &rl) {
        // backoff using rl.RetryAfter; reconcile this create by ClientOrderID
    }
    if errors.Is(err, sdkerrors.ErrPolyester) {
        log.Println(err)
    }
}

A call whose context is canceled or passes its deadline returns a *TransportError for which errors.Is(err, context.Canceled) or errors.Is(err, context.DeadlineExceeded) is true, on every API call, including retried reads. Orders.WaitForOrderTradesComplete timing out also wraps context.DeadlineExceeded. Match these with errors.Is, not on the message.

There is no separate catalog-conversion error type like TypeScript. Catalog / precision failures typically surface as *ValidationError or *APIError.

sdkerrors.IsRetryable(err) identifies failures that may succeed after backoff. sdkerrors.MutationOutcomeUnknown(err) identifies failures where a mutation may already have been applied; reconcile first and reuse the original request identity. It includes every order error code ending in _OUTCOME_UNKNOWN, which IsRetryable does not report: read the order or trigger back before sending it again.

sdkerrors.IsOrderAlreadyTerminal(err) identifies a cancel of an order that has already ended. sdkerrors.Violations(err) returns the fields an order refusal names (FieldPath, RuleID, Message).

*ResponseContractError is deliberately non-retryable, but MutationOutcomeUnknown(err) == true: the server returned success yet omitted a required ID, reported an invalid status, or disagreed with per-item/count outcomes. Reconcile before deciding whether to resubmit.

Realtime token HTTP failures populate AuthError.Status, Code, Context, Endpoint, Label, and bounded Body. A 403 is a non-transient permission failure: inspect Code and provision the required API-key policy before retrying.

Auth codes

sdkerrors.AuthErrorCode(err) names why credentials or a session were refused, the same way for both transports, such as AUTH_SIGNATURE_INVALID. It returns only auth reasons, and "" otherwise; read APIError.Code for other codes. Compare with the AuthCode* constants, such as AuthCodeSignatureInvalid, AuthCodeKeyExpired, and AuthCodeIPNotAllowed.

IsSessionRequired and IsSubaccountOwnerRoleLocked test the matching error types. Those types unwrap to *APIError, so use errors.As rather than a direct type assertion.

MFA helpers

For session/JWT products sharing auth error codes (not API-key create-key flows on this SDK):

• IsMFAEnrollmentRequired, IsStepUpRequired, IsMFAElevationRequired, IsMFALastFactorRequired

Creating API keys requires a JWT/session client; do not invent Create API key methods here.

Retry sketch

Classify with IsRetryable, then back off. Reconcile a single-order create by its stable ClientOrderID; retained reuse returns a duplicate conflict, not the earlier result. Reuse replayable requestID / clientTriggerID values; withdrawals also reuse their required key, nonce, and signed payload. On subscriptions, *QueueOverflowError means resubscribe after catching up, not a unary retry.

See Requests & idempotency.

Related

• Error handling guide
• Streaming

Related Topics