Skip to main content

Error Codes

When a Platform Interface call cannot succeed, return a JSON body shaped as { code, message } with an HTTP 400. Simpler reads the body only when the status code is exactly 400 — any other 4xx (e.g. 404, 422) is treated as a generic failure and its code is ignored, and a code returned with a 2xx status is not treated as an error. The code field is the machine-readable identifier Simpler uses to surface a localized message to the shopper in the checkout UI; the message field is partner-supplied context (useful in logs but not directly shown).

Catalog​

The canonical error codes are defined in the OpenAPI spec (api/quotes/path.yml). INVALID_PRODUCT and OUT_OF_STOCK_PRODUCT also apply to the /products endpoint; the rest apply to /quote.

CodeScopeWhen to returnWhat the shopper sees
OUT_OF_STOCK_PRODUCT/products, /quoteOne of the requested products is out of stock in your catalog.Notice that the product is unavailable; the shopper is prompted to remove it or choose another.
INVALID_PRODUCT/products, /quoteA product ID in the request does not exist in your catalog.Generic "this item is no longer available" message.
UNSHIPPABLE_LOCATION/quoteThe requested shipping address is outside the regions you serve."We can't ship to this location" prompt; shopper is asked to edit the address.
UNSHIPPABLE_CART/quoteThe cart as a whole cannot be shipped (e.g. weight/volume limits, mixed-region items)."This cart can't be shipped" prompt; shopper is asked to modify the cart.
INVALID_COUPON/quoteThe coupon code supplied is not recognized."Invalid coupon" inline error on the coupon input.
INAPPLICABLE_COUPON/quoteThe coupon exists but does not apply to this cart (e.g. minimum spend not met)."This coupon can't be applied" inline error on the coupon input.

Closed set vs. custom codes​

Only the codes above influence the shopper-facing Simpler checkout UI. Partners may return other code values for internal debugging or logging — Simpler will treat unknown codes as a generic failure and surface a neutral message to the shopper. If you need a new UI-affecting code, reach out to Integrations Support.

Example​

{
  "request_id": "af4ebaa6-7f47-4163-85af-d5b82a8cf4b0",
  "code": "OUT_OF_STOCK_PRODUCT",
  "message": "Product 'product-id-1' is out of stock"
}

See also​