Guides

Errors

The API uses standard HTTP status codes and returns a JSON error object explaining what went wrong.

On this page

The error object
Error types & status codes
Validation errors
What to retry

The error object

JSON

{
  "error": {
    "type": "not_found",
    "message": "No such product: 1042."
  }
}

Field	Description
`type`	One of the types below. Branch on this, not on `message`.
`message`	A human-readable explanation. Wording may change.
`param`	Optional. The request field the error is about.
`errors`	Optional. Validation messages keyed by field path.

Error types & status codes

Type	HTTP status	Meaning
`invalid_request`	400, 422	The request is malformed or failed validation. Check `param` and `errors`.
`authentication`	401	The API key is missing, invalid, expired or revoked.
`permission`	403	The key lacks a required scope, or the plan doesn't include API access.
`not_found`	404	The resource doesn't exist in this store (or the path is wrong).
`conflict`	409	The resource's state doesn't allow this action, or an Idempotency-Key was reused with a different body.
`rate_limited`	429	Too many requests. Wait for `Retry-After` seconds.
`server`	500, 503	Something went wrong on our side. Safe to retry with backoff.

Validation errors

When a body fails validation you get 422 with every problem listed. Nested fields use dot paths, with array indexes as numbers:

422 Unprocessable Content

{
  "error": {
    "type": "invalid_request",
    "message": "The given data was invalid.",
    "param": "variants.0.price",
    "errors": {
      "variants.0.price": [
        "The price must be at least 0."
      ],
      "title": [
        "The title field is required."
      ]
    }
  }
}

What to retry

Don’t retry 400, 401, 403, 404 or 422 without changing the request.
Retry after waiting on 429 — see rate limits.
Retry with exponential backoff on 5xx and network errors. For POST requests, send an Idempotency-Key so a retry can’t create a duplicate.