Skip to main content
Ambient returns a stable error code and a human-readable message. HTTP responses also include X-Request-ID; retain it when reporting an unexpected failure. Clients should branch on the code, not the message.

​
Decide whether to retry

​
Authentication exchanges

The retry advice above applies to market commands, not one-use authentication proofs. With OAuth connections, a consumed code or refresh-token replay revokes its token family. Renew using the current refresh token, or reconnect if the exchange result was lost. Reconnecting creates a new actor/grant, so recover an uncertain market outcome before resubmitting; the old actor’s command ID does not provide deduplication for the new actor.

​
Preserve idempotency

A command ID belongs to one authenticated actor and one exact request. Reusing that ID with identical content returns the stored decision. Reusing it with different content returns idempotency_conflict. This distinction matters after a timeout. An unknown result is a retry of the same command. A decision to change a market version, amount, schema, authority, or any other input is a new command.

​
Recover authoritative state

Do not infer a private result from public activity:
  • participants use GET /v1/markets/{marketId}/my-outcome or get_my_market_outcome;
  • requesters use their scoped offer read before selecting RFO offers;
  • creators use GET /v1/markets/{marketId}/record or get_market_record;
  • lottery creators use get_lottery_review while the market is open, since the complete audit returns 403 until resolution; and
  • asynchronous payment callers poll the payment operation returned for their command.
The available creator record contains ordered market history and a content hash. Direct-claim, request-for-offers and lottery records also report a successful state reconstruction check. Independent sealed-auction reconstruction is not yet implemented, so its record reports stateReconstructed: false.

​
Report an unexpected failure

Capture the HTTP status, stable error code, X-Request-ID, command ID, and route. Do not include bearer tokens, private keys, email codes, payment credentials, or private offer content.