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
| Type | When |
|---|---|
*AuthError | Missing/invalid credentials; realtime HTTP errors include structured context |
*ValidationError | Bad SDK input (post_only, enums, shapes, precision) |
*TransportError | Network / timeout, usually retryable with backoff |
*RateLimitError | Rate limited; optional RetryAfter *float64 |
*ServerError | Backend 5xx |
*APIError | Structured Connect/API error (Code, Metadata) |
*ResponseContractError | Successful mutation response was incomplete or internally inconsistent |
*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)
}
}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.
*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.
MFA helpers
For session/JWT products sharing auth error codes (not API-key create-key flows on this SDK):
IsMFAEnrollmentRequired,IsStepUpRequired,IsMFAElevationRequired,IsMFALastFactorRequired,AuthErrorCode
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.