Error handling
A Storefront API client must handle three independent failure layers: transport and HTTP failures, top-level GraphQL errors, and typed business errors returned by mutation payloads.
Keep these layers separate in application code. They have different retry rules, logging requirements, and customer-facing recovery paths.
Transport and GraphQL errors
DNS, TLS, connection, timeout, and non-GraphQL HTTP failures can leave mutation outcome unknown. Reconcile the affected cart, payment session, or order before repeating a state-changing request.
The response’s top-level errors array covers invalid documents or variables, authentication, authorization, and unexpected resolver failures. Preserve usable partial data while deciding whether a failed field is essential to the current screen.
Log the operation name, error message, path, safe extensions, and your request correlation ID. Never log credentials, passwords, raw payment details, or unnecessary personal data.
Typed business errors
Cart and customer mutations expose business validation through their payload errors field. Always select __typename, then add fragments for the details your user interface needs.
Use __typename as the stable dispatch key. Human-readable messages are display and diagnostic text; do not parse them to control application behavior.
Treat a non-empty payload error list as a failed or partially failed business operation unless that mutation’s contract explicitly states otherwise.
Retry by operation type
Retry read queries after transient transport failures with bounded exponential backoff and jitter.
For ordinary cart mutations, check the current cart after an ambiguous failure before deciding whether to repeat the operation. Fix validation, authentication, and permission failures before retrying.
Never automatically repeat payment initialization or cart completion without reconciling the cart, payment session, or order first. These operations can succeed even when the client did not receive the response.