Error Handling
Classify transport, GraphQL, validation, authorization, payment, and business failures safely.
Handle failures by layer. Do not infer business success from an HTTP response alone, and do not expose raw upstream details to customers.
Error Taxonomy
| Layer | Examples | Partner response |
|---|---|---|
| Local validation | Missing or malformed partner input | Reject before sending; associate feedback with the field |
| Transport | DNS, TLS, connection, or timeout failure | Record safe diagnostics; assess retry eligibility |
| HTTP | Non-success response from an approved endpoint | Follow documented semantics only; preserve correlation data |
| GraphQL protocol | Top-level errors returned with or without data | Treat each required operation result as unconfirmed until evaluated |
| Authentication or authorization | Invalid, expired, or insufficient access | Stop; verify configuration through the approved support path |
| Business validation | Request conflicts with product or workflow rules | Show an actionable, non-sensitive message; do not retry unchanged input |
| Payment or finalization | Payment, bind, or modification does not reach verified completion | Keep the transaction pending or failed; reconcile server-side |
Safe Error Record
Capture the operation name, environment label, timestamp, safe correlation identifiers, outcome category, and sanitized message. Do not log credentials, card data, tokens, full customer payloads, or sensitive browser event details.
Customer Experience
- Use a clear summary and an actionable next step.
- Preserve entered data where safe.
- Associate validation errors with fields.
- Announce dynamic errors to assistive technology.
- Avoid exposing stack traces, internal hostnames, or upstream response bodies.
- Provide a support reference that maps to sanitized server logs.
Partial GraphQL Responses
GraphQL can return data and errors together. Validate the fields required for the current state transition. Do not proceed to purchase, bind, or confirmation when required result data is absent or ambiguous.
Continue with Retries & Idempotency.