Errors & retries

Every JSON error body has the same top-level shape:

{ "code": "seller_unreachable", "error": "the selected seller could not be reached" }

code is the stable value for program logic. error is human-readable detail and may change without a version change. Those two fields are the whole envelope, on every endpoint and every status: there is no message, and no error_code echoing code. A client that reads error reads every Spot error.

Bodies served before 2026-08-29 could also carry message and error_code. The official SDKs still accept both spellings, and will stop doing so after 2027-02-28.

Retry rules

• Retry GET requests after transient 502, 503, or 504 responses with exponential backoff.
• On 429, wait for Retry-After; it is authoritative.
• Do not blindly retry a state-changing request after an ambiguous transport failure. First reconcile the order, contract, or trade through its read API.
• Seller registration is idempotent by endpoint_url when the body and current ownership credentials are unchanged.
• 402, 409, 410, and 425 describe market, balance, or contract state; changing the request or waiting for that state to change is required.

Codes

An endpoint may return a subset of these codes. Its reference page and OpenAPI operation define the applicable statuses.