Error handling

Thor GraphQL clients need to handle three distinct failure layers. Keeping them separate produces clearer user messages and safer retries.

1. Transport failures

DNS, TLS, timeout, connection, and non-GraphQL HTTP failures mean the client may not know whether a mutation ran. Do not blindly repeat payment or order completion. Re-query the affected cart, order, or session first.

2. Top-level GraphQL errors

The response’s top-level errors array covers invalid documents or variables, authentication, authorization, and unexpected resolver failures. GraphQL may return both data and errors, so preserve usable data while deciding whether the failed field is essential.

Log the error message, path, safe extensions, operation name, and your request correlation ID. Never log access tokens, passwords, raw payment details, or unnecessary personal data.

3. Typed mutation payload errors

Business validation is returned in the mutation payload’s errors field. Always select __typename and fragments for details the UI needs:

GraphQL

Code in graphql

Treat a non-empty payload errors list as a failed or partially failed business operation unless that mutation’s contract explicitly says otherwise. Use __typename as the stable dispatch key; do not branch by parsing human-readable messages.

Retry guidance

• Retry read queries on transient transport failures with bounded exponential backoff and jitter.
• Retry ordinary cart mutations only after checking current cart state.
• Do not automatically retry payment initialization or cart completion without reconciliation.
• Fix validation and permission errors before retrying.
• Show a customer-safe message, while retaining typed technical details in structured logs.