// guide
Errors
Every error has the same shape. Branch on code, show message to a person, and log request_id.
The envelope
{
"error": {
"code": "invalid_request",
"message": "This marketplace trades in USD. Prices must use it.",
"param": "price.currency",
"request_id": "req_7Gq0mR2s9xVbN4kT1pLc"
}
}codeis for your program. A published code never changes meaning. New codes can be added, so handle one you do not recognise by its HTTP status.messageis for people, and may change wording.param, when present, names the field at fault, with dots for nested fields such asprice.currency.request_idis on every response as theRequest-Idheader too. Quote it when you write to us; the dashboard's logs find it.
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
| 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.