Checkout Error

Overview

What qualifies as an error

Checkout errors can occur when validating customer information, calculating an order total, creating a payment request, presenting wallet instructions or processing a return from another service. Examples include an invalid address, unavailable delivery method, expired quote, network mismatch, duplicate submission or a provider timeout. The same visible symptom can have very different consequences. A form validation error may be fixed immediately, while a timeout after a payment request requires a status lookup before retrying.

Classify the recovery path

Useful categories distinguish customer-correctable input, merchant configuration, payment-provider response, temporary infrastructure failure and unknown transaction state. Each error should have a stable internal code, relevant stage, timestamp, correlation or order identifier, and a customer-safe explanation. Retryability should be based on the actual state, not just the displayed message. A failed network request may have reached the server and created an invoice even when the browser never received the response.

Avoid creating a second payment

When the result is uncertain, check the existing order and payment-request status before generating a replacement. Keep repeated actions tied to a stable request identity where the integration supports it. Never expose secret keys, raw sensitive payloads or internal system details in a public error message. Give the customer a next step that matches the problem: correct a field, choose a supported network, wait for confirmation or contact support with a reference number.

Measure the right outcome

Monitor the error rate by step, client device and release version, but also whether users ultimately complete checkout. One transient error is not the same as an abandoned order. Checkout Recovery focuses on moving safely from an interrupted state to a valid next action.