Overview

Errors

HTTP status codes and error responses.

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

CodeTypeDescription
200-Success
400invalid_request_errorInvalid or missing parameter
401authentication_errorMissing or invalid API key
403authorization_errorNot permitted
404not_found_errorResource doesn't exist
409conflict_errorConflict with the current state
410gone_errorResource is no longer available
429rate_limit_errorToo many requests
500api_errorServer error

Rate limiting is not currently enforced on the public API. 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"
  }
}