API · Errors and limitsDocs navigation

API errors, rate limits and retries

Each key can make 60 requests a minute. Editing and deleting stock share a stricter bucket of 20 a minute.

On this page

Status codes

StatusMeaning
200, 201Done. A create answers 201
202Deliver: another attempt holds the order
400The request is wrong. The message says what
401The key was refused
403The key lacks the scope, or the shop is at a plan limit
404Nothing with that id in this shop
409A conflict. See the endpoint for whether to retry
422Deliver: the order cannot be delivered
429Rate limited
500A fault on the Shoplio side

An id from another shop answers 404, the same as an id that does not exist.

The error body

Error
{ "success": false, "error": "Product not found" }

A refused delivery adds a data object with a machine-readable code. See Deliver an order.

With a valid key, a path that matches no route answers in a different shape:

Unmatched route
{ "error": true, "message": "Cannot GET /api/v1/unknown" }

Rate limits

BucketLimit per keyApplies to
Every request60 a minuteAll 20 endpoints
Stock edits and deletes20 a minute, sharedPATCH and DELETE on a stock item, and the bulk delete
Deliveries60 a minutePOST /orders/:id/deliver

Each key has its own buckets. A request that fails authentication is not counted.

Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. On the stock edit, stock delete and deliver routes these describe the route's own bucket.

A request over a limit answers 429 with a Retry-After header in seconds.

429 Too Many Requests
{
  "success": false,
  "error": "Too many requests. Please wait 12 seconds and try again.",
  "retry_after": 12
}

The 409 busy response

Stock edits and variant creates on one product wait for each other and for stock pushes. Product creates in one shop run one at a time. A write that cannot take its turn within five seconds answers 409 with Retry-After: 5.

Updating a product or a variant and deleting stock take no turn, so they never answer this 409.

Nothing was written, so sending the same request again is correct.

409 Conflict
{ "success": false, "error": "Another change to this shop's products is running right now — try again in a moment." }

What is safe to retry

CallSafe to repeatWhy
Any GETYesIt changes nothing
PATCH a product, variant or stock itemYesIt sets values
POST /orders/:id/deliverYesA delivered order answers already_delivered
DELETE a stock item, bulk deleteYesA deleted id answers 404 or comes back in skipped
POST /products, POST a variantNoA repeat creates a second one
POST stockNoA repeat adds the items again
POST balance add or subtractNoA repeat moves the amount again

After a timeout on a call that is not safe to repeat, read the resource before you send it again.

If the docs do not cover it, ask on Telegram or use the contact form.