Conventions

Errors

Every failure, from a malformed request to an upstream shipping provider outage, comes back with the same JSON shape. There is no HTML error page anywhere under /v1: even a request to a route that doesn't exist returns this envelope.

Envelope

{
  "error": {
    "type": "validation_error",
    "message": "The request payload is invalid.",
    "fields": {
      "price": ["The price must be at least 0.01."]
    }
  }
}

fields is only present when there's field-level detail to attach: validation errors key it by field name, and ambiguous_identifier uses it for the candidate list (see Identifiers). Every other error type omits it entirely rather than sending null.

Error types

Status	type	When
401	authentication_error	No key sent, or the key is unknown, revoked or expired.
403	authorization_error	Valid key, but missing the required scope, or the account's API access isn't enabled or is suspended.
404	not_found	The identifier doesn't resolve to any record, or the route itself doesn't exist.
409	ambiguous_identifier	A friendly identifier matched more than one record. `fields.candidates` lists the matches.
409	conflict	The request is valid but conflicts with the resource's current state (e.g. deleting a listing with an open order).
422	validation_error	The request body or query failed validation. `fields` maps field name to messages.
429	rate_limited	You've exceeded the read or write rate limit. See Rate limits.
502	provider_error	An upstream shipping carrier call failed. Your request was valid; retry the label call later.
varies	http_error	Any other HTTP-level failure not covered above (e.g. an unsupported method on a real route).
500	server_error	Something went wrong on our side. These are logged and reported; if it persists, contact us.

Validation errors

A 422 lists every failing field at once, not just the first one:

{
  "error": {
    "type": "validation_error",
    "message": "The request payload is invalid.",
    "fields": {
      "price": ["The price must be at least 0.01."],
      "quantity": ["The quantity field is required."]
    }
  }
}