Errors and retries

A reliable Thor client handles transport failures, top-level GraphQL errors, and typed payload errors as separate layers. Each layer has different recovery behavior.

Failure layers

Transport and HTTP

DNS, connection, timeout, and non-success HTTP responses can mean the request never reached Thor—or that the response was lost after work began. Log a correlation identifier, operation name, project, and safe resource identifiers. Do not log credentials or sensitive customer and payment payloads.

Retry transient failures with exponential backoff and jitter. Cap attempts and surface persistent failures to an operational queue.

GraphQL errors

Top-level errors can accompany partial data. Inspect both fields. Treat authentication, validation, and selection-set problems as code or configuration issues rather than blindly retrying them.

Typed payload errors

Thor mutations expose business errors in their payloads. Always select the payload’s resource and errors, including __typename and the fields required for a useful message or correction.

GraphQL

Code in graphql

An HTTP 200 response with a null resource or a non-empty payload error list is not a successful business operation.

Retry classification

Retry only when the failure is transient and the operation is safe to repeat. Reads are generally safe. For mutations, first query the affected resource when a timeout or connection loss makes the outcome ambiguous.

Do not automatically retry invalid input, missing resources, authorization failures, stock conflicts, unavailable products, expired discount codes, or payment-provider declines. Those require corrected data, refreshed state, or buyer action.

Payment capture, refund, cart completion, and external integration calls deserve particular care because the remote side may have succeeded. Use stable references and provider idempotency support where available.

Batch operations

Bulk payloads can report per-item failures. Keep a ledger that maps each input to its result, retry only failed inputs, and preserve stable external keys such as SKU. See Bulk operations and sync jobs.

Storefront recovery

On a cart mutation failure, fetch the latest cart before asking the buyer to repeat an action. Prices, availability, discounts, shipping methods, and payment eligibility may have changed since the UI rendered. The Storefront-specific flow is covered in Storefront error handling.