Errors

The Admin and Storefront APIs return errors as Problem Details with a stable code that identifies the case:

Error response

{
  "title": "Not Found",
  "detail": "Product 7204558912004325377 does not exist.",
  "status": 404,
  "code": "Catalog.ProductNotFound",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Field	Content
`title`	Short summary of the error.
`detail`	Explanation in English for developers. Its text may change.
`status`	HTTP status.
`code`	Identifier of the case. Use it in your code to decide what to do.
`traceId`	Request identifier. Include it when you contact support.

Codes and their status are listed in Error codes.

Validation

A validation 400 has code: "Common.Validation", errors with the messages in English, and fieldErrors with one code per field:

Error response

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "code": "Common.Validation",
  "errors": {
    "limit": ["The limit must be between 1 and 200."]
  },
  "fieldErrors": {
    "limit": ["Fields.Range"]
  }
}

A URL or header parameter with the wrong type, such as limit=abc, gets the same response, keyed by the parameter name.

fieldErrors keys are camelCase paths with indices, such as items[0].sku. The empty key ("") is a form-level error. Translate each code to show the reason next to its field:

Code	Reason
`Fields.Required`	The value is missing.
`Fields.Length`	The text is too short or too long.
`Fields.Range`	The number is outside the allowed range.
`Fields.Email`	The email address is not valid.
`Fields.Format`	The value doesn't match the format.
`Fields.Option`	The value is not one of the options.
`Fields.Invalid`	The value is not valid.

A field can also carry a domain code, such as Search.InvalidFacetFilter.

Background operations

Imports, exports, and other long-running jobs are tracked at GET /v1/operations/{id}. When one fails, errorCode holds the code to show the user and error the diagnostic in English.

OAuth errors

POST /connect/token returns errors in the OAuth 2.0 format:

Error response

{
  "error": "invalid_client",
  "error_description": "The specified client credentials are invalid."
}

Decide based on error. Common values are listed in User authorization.

What to do by status

Status	Meaning	What to do
`400`	Invalid body, parameter, or transition.	Fix the request.
`401`	The token is missing or expired.	Get a new token and repeat.
`403`	The token lacks the permission, store, or seller.	Check the application's permissions and the context.
`404`	The resource doesn't exist in the token's store or seller.	Check the identifier and the context.
`409`	The resource's current state blocks the operation.	Read the resource and decide from its new state.
`429`	You exceeded a rate limit.	Wait for the seconds in `Retry-After` and repeat.
`500`	Internal error.	Repeat with growing waits if the operation is safe to repeat.
`503`	The service is busy or unavailable.	Wait a few seconds, or those in `Retry-After`, and repeat.

Retries

A 429, or a 503 with code: "Storefront.Busy", was rejected before it ran: repeat it. After a 500 or a network failure, repeat only what can't be duplicated:

Reads (GET).
Writes with an idempotencyKey in the body, such as order payments, refunds, returns, and cancellations with refund. Repeat with the same key and the operation applies once.

For other writes, read the resource before repeating and confirm whether the first attempt went through.

Errors

Validation

Background operations

OAuth errors

What to do by status

Retries

On this page