Recover from storefront errors
Recover from storefront errors
Make each failure recoverable from the screen where the buyer encounters it. Keep their selected variant, entered address, and cart identity while refreshing the server state needed to continue. Errors and retries defines the transport, GraphQL, and business-error layers; this guide applies them to the interface.
Match the action to the failure
| Situation | Buyer-facing behavior |
|---|---|
| Product read temporarily fails | Keep the page shell and offer a bounded retry |
| Product is absent | Show an unavailable product page, not an endless loading state |
| Cart line has no price | Explain that the item is unavailable in this market |
| Requested quantity is unavailable | Refresh the line and let the buyer adjust or remove it |
| Shipping becomes ineligible | Preserve the address and ask for another returned option |
| Customer session expires | Restore sign-in and refresh customer-sensitive data |
| Payment result is uncertain | Show a checking state and reconcile before another attempt |
Select actionable errors
Use __typename as the dispatch key and handle unknown types with a safe fallback.
A null cart or a non-empty business error list is not proof that an item was added.
Avoid success toasts or optimistic checkout transitions before inspecting the response.
Preserve usable partial data
Top-level GraphQL errors can accompany partial data. Decide whether the failed field is essential to the current screen. A missing optional filter panel may allow product results to remain visible. A missing payable amount must prevent final submission until the cart can be verified.
Reconcile uncertain writes
After a timeout, read the current cart before repeating an add or update. For payment or completion, follow order-placement recovery and inspect the current payment/session state as needed. Do not show an unchanged Pay button that silently starts another attempt.
Verify the recovery paths
Exercise failures in a test client or mocked transport rather than changing live stock to provoke an error. Check that repeated clicks do not create duplicate writes, refreshed data replaces stale totals, and private technical details stay out of the UI. Log a safe correlation ID and error type so support can connect the screen to the request.