Skip to content

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.

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 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.

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 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.