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.
Envelope
Section titled “Envelope”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.
Statuses
Section titled “Statuses”| 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].
Retrying a create request
Section titled “Retrying a create request”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.