Errors

The API uses standard HTTP status codes and returns errors in a consistent JSON envelope.

Response format

Every error returns an error object:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "sort must be one of: created_at, name, price",
    "param": "sort"
  }
}

• type - broad category (see the table below)
• code - specific, machine-readable code
• message - human-readable description
• param - the offending parameter, when applicable

HTTP status codes

Requests are rate limited per IP. A 429 response includes a Retry-After header. See Rate Limits.

Authentication errors (401)

Returned when the Authorization header is missing or malformed, the key isn't found, or the store is inactive.

{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid API key"
  }
}

Validation errors (400)

Returned when a query parameter is invalid. The param field names it.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "limit must be a positive integer",
    "param": "limit"
  }
}

Not found errors (404)

Returned when the URL does not match a known route or the requested resource does not exist.

{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "Resource not found"
  }
}

Rate limit errors (429)

Returned when you exceed the per-IP request limit. The response carries a Retry-After header with the number of seconds to wait before retrying. See Rate Limits for the limits and how to handle them.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests, please try again later"
  }
}

A separate, coarser limit runs at the network edge and can also return a 429 when one IP sends an unusually high volume of requests in a short window. That response comes straight from our network layer, so it is not the JSON envelope shown here and carries no RateLimit-* or Retry-After headers. See Rate Limits.