Skip to content

The ShopSynch API uses standard HTTP status codes to show if a request succeeded or failed.

HTTP status codes ​

StatusNameMeaning
200OKThe request succeeded.
201CreatedThe API created a new resource, for example an order, a product, or a customer.
400Bad RequestThe request is not valid. A parameter is wrong, a required field is missing, or the data format is wrong. For example, the cart is empty at checkout.
401UnauthorizedAuthentication failed or is missing. The API key or the JWT token in the request is not valid.
404Not FoundThe resource does not exist. It was deleted or it never existed.
422Unprocessable EntityValidation failed. The data that you sent does not pass the required checks. The response lists each field with an error.
5xxServer ErrorAn error occurred on the server. Report the error immediately. It can show a system problem.

Error response format ​

An error response has status set to false and a message.

json
{
  "status": false,
  "message": "Your cart is empty. Please add items to your cart before proceeding."
}

Handle errors ​

  • Check the HTTP status code of each response.
  • If authentication fails, make sure that the API key or the JWT token is valid and that you send it in the request headers.
  • Retry a request only if the error is a 5xx error.

Error Reference ​

Cart and Storefront Errors ​

HTTP StatusMessageDescription
400Please log in or start a guest session to continue.The request has no Authorization header and no X-Session-Id header.
400Please start a guest session first.A guest checkout request has no X-Session-Id header.
410This v1 endpoint has been deprecated. Please integrate with the equivalent v2 endpoint.You called a removed /v1/products/* or /v1/carts/* endpoint. See Migrate from V1 to V2. The errorCode is API_VERSION_DEPRECATED.
400Your cart is empty. Please add items to your cart before proceeding.You started checkout with an empty cart.
400Please select all required options before adding this item to your cart.A V2 add-to-cart request does not select a variant group and a SKU for a product that has options.
400The requested quantity is more than what we have in stock. Only N items are available.The quantity is more than the available stock.
400'PRODUCT' is no longer available.The product is archived.
404The specified item could not be found in your cart.The cart item ID does not exist in the cart.
404Product not foundThe product ID or slug does not exist.

Promotion Errors ​

HTTP StatusError CodeDescription
400INVALID_DISCOUNT_TYPEUnknown value passed for discountType
400DISCOUNT_VALUE_REQUIREDdiscountValue missing for PERCENTAGE or FLAT_AMOUNT
400QUANTITY_FIELDS_REQUIREDrequiredQuantity or freeQuantity missing for BUY_X_GET_Y
400END_DATE_BEFORE_START_DATEendDate is before startDate
400INVALID_STATUS_TRANSITIONAttempted an unsupported status transition
400CANNOT_SET_DEPLETED_STATUSDEPLETED cannot be set manually
409PROMOTION_CODE_ALREADY_EXISTSA promotion with that code already exists for your tenant

Order / Checkout Errors ​

HTTP StatusError CodeDescription
400PROMOTION_NOT_ACTIVEThe promotion code exists but is not currently active
400PROMOTION_MINIMUM_NOT_METOrder subtotal is below the promotion's minimumOrderValue
400PROMOTION_USAGE_LIMIT_REACHEDThe promotion has been fully redeemed
400PROMOTION_CUSTOMER_LIMIT_REACHEDThis customer has already used this promotion the maximum number of times
404PROMOTION_NOT_FOUNDNo promotion found for the provided code
409PROMOTION_ALREADY_APPLIEDA promotion has already been applied to this order

Next Steps ​

Build with joy