Skip to content

Errors

Every Shop API error has one format, and the reaction to it is keyed off the status and the field, never off the text.

Every error is an object with a single message field:

{
"message": "Unauthenticated."
}

A 422 adds errors — a flat map whose key is the field path and whose value is a list of messages:

{
"message": "The items.0.price field must be an integer.",
"errors": {
"locale": ["The locale field is required."],
"items.0.price": ["The items.0.price field must be an integer."]
}
}

For nested fields the path is literal and dotted: items.0.price, items.3.interval_unit. The text in message and errors follows Accept-Language (field names are translated too), so key logic off the status and the field key, never off the text.

Status When What to do
401 the key is missing, unknown or already regenerated stop and surface it: the integration is misconfigured. See Authentication
429 60 failed key attempts were made from your address within a minute fix the key, wait a minute
404 the order or product is not this shop’s, or does not exist for an order — open a new one; for a product — check the external_id
409 the order is no longer a draft: checkout has started, or it was cancelled open a new order and hand the widget the new id. See Orders
422 validation fix the payload; errors names the field

The Shop API returns no other client-error statuses. A 5xx is a failure on the Neocarts side: retry a little later, and if it persists write to [email protected].

POST /v1/shop/orders/create is not idempotent: if your server retries it after a timeout or a dropped connection, Neocarts opens a second order in draft. That is harmless — a draft nobody paid charges nothing and creates nothing. Hand the widget the id of the order whose response you actually received and simply forget the other one.