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. 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). Today all documented codes are scoped to the /quote endpoint.

CodeScopeWhen to returnWhat the shopper sees
OUT_OF_STOCK_PRODUCT/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/quoteA product ID in the quote 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": "req_abc123",
  "code": "OUT_OF_STOCK_PRODUCT",
  "message": "Product 'product-id-1' is out of stock"
}

See also​