Errors
When a request fails, the API answers with a 4xx or 5xx status and a JSON body that says why. This guide shows the body shapes, what each status means, how to branch on an error code, and which failures you can retry.
The error body
Section titled “The error body”Business errors come from EcomWeb’s own rules, such as a resource that does not exist or a name that is already taken. They have a stable code you can branch on.
{ "code": "DOMAIN_TAKEN", "message": "This domain is already in use.", "details": { "field": "custom_domain" }, "timestamp": "2026-11-17T09:30:00.000Z"}details is optional and its content depends on the error. Some business errors carry extra fields next to code. A not found error, for example, has resource and identifier instead of details, and a permission error can have resource and action. Always read code, message and timestamp, and treat anything else as extra context.
Plain HTTP errors come from the API’s framework and from key checks, so every authentication failure in the authentication guide has this shape. There is no code.
{ "statusCode": 401, "message": "Invalid API key", "error": "Unauthorized"}Validation errors come from checking the request body or query string. They are plain HTTP errors with status 400, and message is a list with one entry for each problem.
{ "statusCode": 400, "message": [ "limit must not be greater than 10000", "sort_order must be one of the following values: asc, desc" ], "error": "Bad Request"}Some routes check their input themselves and return a business error with the code VALIDATION_FAILED instead. Its details.errors lists each field:
{ "code": "VALIDATION_FAILED", "message": "email is required", "details": { "errors": [{ "field": "email", "message": "email is required" }] }, "timestamp": "2026-11-17T09:30:00.000Z"}The API removes request fields it does not know instead of rejecting them. If a field you send has no effect, check its spelling.
Request bodies can be up to 50 MB of JSON. A larger body is refused with status 413, and the body of that response is not a documented shape.
To tell the shapes apart in code, check for code:
async function readError(res: Response) { const body = await res.json().catch(() => ({})) if (typeof body.code === "string") { return { status: res.status, code: body.code, message: body.message } } // A plain HTTP error or a validation error: message is a string or a list const message = Array.isArray(body.message) ? body.message.join(", ") : body.message return { status: res.status, code: undefined, message }}Status codes
Section titled “Status codes”| Status | Meaning | When it happens |
|---|---|---|
| 400 | Bad request | The request is malformed or fails validation, or a business rule refuses it |
| 401 | Unauthorized | The key is missing, unknown, paused, revoked or expired |
| 403 | Forbidden | The key is valid but may not do this: a missing scope, a read-only key, a publishable key on a Store API route, an IP address or origin that is not allowed, or a role that is too low |
| 404 | Not found | The resource does not exist in this store, or the store does not exist |
| 409 | Conflict | The request conflicts with the resource’s current state, for example a domain already in use or a theme that is live |
| 413 | Payload too large | The JSON body is over 50 MB |
| 422 | Unprocessable | Used by a few routes, for example some shipping and promotion checks, when a request is valid but cannot be carried out |
| 429 | Too many requests | You hit a rate limit, see the rate limits guide |
| 500 | Server error | Something failed on EcomWeb’s side |
The cause of a 401 or 403 is in message. The authentication guide lists every message.
Error codes
Section titled “Error codes”Use code to branch, because message can change. These are the codes you are most likely to meet:
| Code | Status | Meaning |
|---|---|---|
VALIDATION_FAILED |
400 | One or more fields are invalid, see details.errors |
ACCESS_DENIED |
403 | The caller may not do this |
INSUFFICIENT_ROLE |
403 | The signed-in user’s role in the store is too low |
NOT_STORE_MEMBER |
403 | The signed-in user is not a member of the store |
NOT_STORE_OWNER |
403 | Only the store owner can do this |
SUBSCRIPTION_REQUIRED |
403 | The store’s plan does not include this feature |
<RESOURCE>_NOT_FOUND |
404 | The resource is missing. The prefix is the resource name in capitals, for example PRODUCT_NOT_FOUND |
DOMAIN_TAKEN |
409 | The custom domain belongs to another store |
THEME_IS_LIVE |
409 | The theme is the live theme and cannot be changed this way |
AUTH_RATE_LIMITED |
429 | Too many sign-in requests from one address, see below |
Other routes return their own codes, for example SETUP_RUNNING or SOURCE_NOT_UPLOADED. Each operation in the API reference lists the statuses it can return. Treat an unknown code as a failure of that status and show message.
Retrying
Section titled “Retrying”Retrying is safe when the same request cannot do harm twice.
| Status | Retry? |
|---|---|
| 429 | Yes, after a wait, see Handle a 429 |
| 500, 502, 503, 504 | Yes for reads, with a growing wait. For a write, first check whether it was applied, because a second try can create a duplicate |
| 400, 401, 403, 404, 409, 413, 422 | No. The same request fails the same way. Fix the request, the key or the state first |
A network error with no response is like a 5xx. Retry a read, and check before you retry a write.