Errors and retries
Errors and retries
A Thor request can fail at the transport, GraphQL, or business-operation layer. Inspect each layer before deciding whether the action succeeded. An HTTP 200 response alone is not a successful purchase or update.
Classify the result
| Layer | Examples | Response |
|---|---|---|
| Transport or HTTP | Timeout, connection loss, unavailable service | Retry reads with limits; reconcile uncertain writes |
Top-level GraphQL errors | Invalid document, missing permission, failed field | Correct the document or access; inspect partial data |
Mutation payload errors | Invalid input, unavailable stock, rejected operation | Handle typed errors and refresh affected state |
Select __typename for business errors and the available details your client can act on.
Dispatch on the type, not by parsing a human-readable message.
Handle unfamiliar error types with a safe fallback.
A write timeout is an unknown result
The server may have accepted a mutation before the connection failed. Before repeating creation, inspect the resource using the stored ID or your stable external mapping. Before repeating a payment action, inspect current payment state and the provider reference. Use the documented same-cart recovery for order placement.
Only retry an unchanged request when the failure is transient and repeating that operation is safe. Use bounded backoff and jitter for retryable reads. Invalid input, missing permission, and payment declines need correction or user action.
Bulk results need their own contract
Do not infer partial success from an errors list.
Some bulk operations fail the entire batch.
Keep source identifiers and a batch ledger, then follow the specific mutation’s documented recovery unit.
See Bulk operations and jobs.
Useful diagnostics
Keep the operation name, safe resource IDs, response status, error type, and an available request or correlation ID. Do not log credentials, raw customer payloads, or payment details. See Recover from storefront errors for buyer-facing behavior.