Error Handling
All state endpoints can return a range of HTTP status codes indicating the result of the operation or specific issues encountered. These errors may stem from validation, business rules, session state, or system-level problems. Clients should interpret these codes consistently across endpoints and provide appropriate feedback to users.
| Status Code | Description |
|---|
400 | Bad Request – the request was malformed or contained invalid parameters. |
401 | Unauthorized – session may have expired, or credentials are missing/invalid. |
402 | Payment Required – returned only by the order confirmation/execute endpoint. |
403 | Forbidden – action is not permitted for the current user or session. |
404 | Resource not found – e.g., basketId missing from session context. |
405 | Method Not Allowed – returned by basket item update and payment option select/update. |
406 | Not Acceptable – the order is missing information, basket item quantity is unavailable, payment method is disabled, or gift card has no balance. |
409 | Conflict – duplicate resource (e.g., loyalty card already attached, gift card already attached). |
410 | The requested resource is no longer available (e.g., confirmed order). |
412 | Precondition Failed – order data integrity failed, insufficient membership points, failed to update payment method, no ongoing order or customer, or dependency failed. |
417 | Customer account was deleted or blocked. |
422 | Validation error – input data does not meet the required schema. |
423 | Resource is locked – e.g., basket or order is currently in use or updating. |
424 | Dependency failure – another service or operation failed. |
451 | Access restricted due to legal reasons. May include an error body for details. |
460 | Custom status code returned only by the address PUT endpoint when address validation returns suggestions. |
| Status Code | Description |
|---|
500 | Internal server error – unexpected condition or system fault. Returned by every endpoint except GET /config, which only returns 401. |
- Treat
4xx errors as user-facing issues and display actionable or explanatory messages. - Treat
5xx errors as system failures, suggest retry or escalate to support. - Handle
401 and 403 by redirecting to login or refreshing the session. - For
422, parse the validation details (if present) and highlight specific input issues. 423, 424, and 412 may indicate transient issues – consider retry logic with delay.- For
460 returned by the address PUT endpoint, parse the suggested address payload and present the suggestions to the customer for confirmation.
