Errors

The Store API error format, HTTP statuses, and recovery paths.

Store API errors share one response format. Use the HTTP status for the broad handling path and error.code for the specific condition. Error messages are always in English, whatever language the store or request uses, so do not show them to shoppers or merchants as they are.

Envelope#

json

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Invalid token"
  }
}

Field	Meaning
`success`	Always `false` for an error response.
`error.code`	Stable identifier for programmatic handling.
`error.message`	English explanation for developers and logs; do not branch on it.
`error.details`	Optional structured context documented by the endpoint.
`error.params`	Optional values used in the message, included by some errors.

Status codes#

Status	Meaning	Next step
400	The input is malformed or invalid.	Correct the request using the endpoint's error code and details.
401	Authentication failed.	Get a valid token; do not retry the same rejected token. Authentication lists each code.
402	An active subscription, quota, or credit balance is required.	Resolve the condition identified by `error.code`; retrying the unchanged request will not help.
403	The token's scopes, its pinned API version, or the store's plan does not allow the operation.	Check `error.code`, required scopes, API version, and endpoint prerequisites.
404	The route or store-scoped resource was not found.	Check the path, identifier, and token's store.
405	The path does not support this HTTP method.	Use one of the endpoint's documented methods.
409	The request conflicts with current state.	Follow the endpoint's documented recovery flow.
410	A session, upload, or other temporary resource has expired.	Create a replacement and retry with its new identifier.
422	A valid request cannot be processed in the current resource state.	Correct the condition identified by the error code.
429	The rate limit was reached.	Wait for `Retry-After`.
5xx	Tringify could not complete the request.	Retry idempotent operations with backoff; check whether a write succeeded before retrying it.

Endpoint errors#

Each endpoint lists the errors specific to that operation. Authentication (401), subscription (402), API-version or scope (403), method (405), and rate-limit (429) errors can occur before the endpoint runs and may not be repeated in every endpoint's error list. An endpoint's 401 row summarizes authentication failures; Authentication lists each code and when it is returned.

Keep the response's X-Request-ID when investigating an error or contacting support. Share the status and error code with it; do not include your bearer token.