// guide

Errors

Every error has the same shape. Branch on code, show message to a person, and log request_id.

The envelope

400 POST /v1/listingsresponse

{
  "error": {
    "code": "invalid_request",
    "message": "This marketplace trades in USD. Prices must use it.",
    "param": "price.currency",
    "request_id": "req_7Gq0mR2s9xVbN4kT1pLc"
  }
}

code is for your program. A published code never changes meaning.
message is for people, and may change wording.
param, when present, names the field at fault, with dots for nested fields such as price.currency.
request_id is on every response as the Request-Id header too. Quote it when you write to us; the dashboard's logs find it.

Statuses

HTTP statuses
status	code	means
400	`invalid_request`	A field is missing or wrong. param names it.
401	`api_key_missing, api_key_invalid`	No key, or not one of ours.
403	`for example seller_not_verified`	The key may not do this, or a rule of the marketplace forbids it.
404	`resource_missing`	No object with that id in this marketplace, in this mode.
409	`invalid_state, and others`	The object is not in a state that allows this. The message names the state.
429	`rate_limited`	Too many requests for this key. Wait for Retry-After seconds.
500	`internal_error`	Our fault. Retry with the same Idempotency-Key.

Codes worth handling

Error codes
code	means
`invalid_state`	An order, dispute, or payment cannot make that change from where it is. The message names the current state.
`actor_not_permitted`	The actor is a party to the order, but not the one who may do this now, such as a claimant confirming their own claim.
`actor_not_party`	The actor is not the order's buyer or seller.
`quantity_unavailable`	Someone else reserved the last unit first.
`self_order`	A buyer and seller with the same external_id cannot trade with each other.
`seller_not_verified`	Seller verification is on and this seller is not verified yet.
`seller_suspended`	The seller is suspended and cannot publish or take orders.
`prohibited_content`	The listing contains a word your marketplace prohibits.
`category_prohibited`	The listing's category is prohibited.
`seller_payouts_not_enabled`	Payments are on and the seller has not finished Stripe onboarding.
`stripe_not_connected`	Payments are on and this mode has no Stripe connection.
`marketplace_read_only`	The marketplace takes reads only: live mode after a missed payment, for example, or both modes while MarketSDK has suspended the workspace. GET /v1/marketplace says why, in read_only.
`idempotency_key_reused`	The Idempotency-Key was used before with a different request.
`already_reviewed`	This party already reviewed this order.
`review_window_closed`	The review window has closed.
`dispute_window_closed`	The dispute window for this completed order has closed.

Anything else, treat by status: fix the request on a 4xx, retry on a 5xx.

next: pagination