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
| Status | Meaning |
|---|---|
| 200, 201 | Done. A create answers 201 |
| 202 | Deliver: another attempt holds the order |
| 400 | The request is wrong. The message says what |
| 401 | The key was refused |
| 403 | The key lacks the scope, or the shop is at a plan limit |
| 404 | Nothing with that id in this shop |
| 409 | A conflict. See the endpoint for whether to retry |
| 422 | Deliver: the order cannot be delivered |
| 429 | Rate limited |
| 500 | A fault on the Shoplio side |
An id from another shop answers 404, the same as an id that does not exist.
The error body
{ "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:
{ "error": true, "message": "Cannot GET /api/v1/unknown" }Rate limits
| Bucket | Limit per key | Applies to |
|---|---|---|
| Every request | 60 a minute | All 20 endpoints |
| Stock edits and deletes | 20 a minute, shared | PATCH and DELETE on a stock item, and the bulk delete |
| Deliveries | 60 a minute | POST /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.
{
"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.
{ "success": false, "error": "Another change to this shop's products is running right now — try again in a moment." }What is safe to retry
| Call | Safe to repeat | Why |
|---|---|---|
Any GET | Yes | It changes nothing |
PATCH a product, variant or stock item | Yes | It sets values |
POST /orders/:id/deliver | Yes | A delivered order answers already_delivered |
DELETE a stock item, bulk delete | Yes | A deleted id answers 404 or comes back in skipped |
POST /products, POST a variant | No | A repeat creates a second one |
POST stock | No | A repeat adds the items again |
POST balance add or subtract | No | A 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.