Errors

The Seller API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed given the information provided.
• Codes in the 5xx range indicate an error with the Whatnot servers (these are rare).

Most error bodies follow RFC 9457 ("Problem Details for HTTP APIs") and are served as application/problem+json. The exception is 422 Unprocessable Content — see Validation errors below.

Attributes

• type (string) A slug identifying the problem type, such as invalid-parameter or product-not-found. Stable for a given kind of error; use it for programmatic branching rather than parsing detail.
• title (string) A short, human-readable summary of the problem type. The same for every occurrence of a given type.
• status (integer) The HTTP status code, repeated here so the body stands on its own.
• detail (string) A human-readable explanation specific to this occurrence of the problem.
• Additional fields may appear depending on type — for example invalid-parameter adds param, naming the request field that failed validation, and missing-scope adds required_scopes.

Handling errors

We recommend writing code that branches on the HTTP status code first, then on type for anything in the 4xx/5xx range, rather than parsing detail, which is meant for humans and may change wording over time.

Example error response

{
  "type": "invalid-parameter",
  "title": "Invalid parameter",
  "status": 422,
  "detail": "Quantity must be greater than or equal to 0.",
  "param": "items.0.quantity"
}

Validation errors

A 422 for a malformed request body or query parameters doesn't follow the type/title/status/detail shape above. Instead it's served as application/json with a detail array, one entry per failed field:

{
  "detail": [
    {
      "loc": ["body", "items", 0, "quantity"],
      "msg": "Input should be greater than or equal to 0",
      "type": "greater_than_equal"
    }
  ]
}

• loc (array) The path to the failing field, as alternating keys and indices starting with body, query, or path.
• msg (string) A human-readable explanation of the failure.
• type (string) A machine-readable validation failure code, such as greater_than_equal or missing.

Best practices

• Check the HTTP status code first, then branch on type for anything in the 4xx/5xx range.
• Retry 429 and 5xx responses with exponential backoff; don't retry other 4xx errors without changing the request.
• For idempotent writes (such as setting or adjusting inventory), reuse the same per-item idempotency_key when retrying so it isn't applied twice.
• Log the request ID from failed responses — it's the fastest way for support to look up what happened.