Errors & retries

Spot fails loudly rather than silently paying more. Two of these codes are market conditions, not faults — handle them and you'll never be surprised by an invoice.

Every error body is { "code": "<code>", "message": "<message>" }.

Market conditions

CODE	TYPE	MEANING	RETRY
402	`no_fill_at_limit`	Nothing in the book clears at or under your ceiling.	Raise limit or downgrade
409	`instrument_delisted`	Every venue in the class failed conformance. Rare, and always logged publicly.	No · fail over
429	`rate_limited`	Account throughput cap reached. Caps scale with cleared volume.	Backoff
451	`region_unavailable`	No qualifying capacity inside the requested jurisdiction.	Widen region
503	`venue_failover`	Serving venue dropped mid-stream and no replacement fit your limit. You are not billed.	Immediate

Idempotency

Send Idempotency-Key on any retry. Replays return the original fill and are never charged twice.

Billing on failure

You are billed only for completed fills. Refusals, failovers and cancellations cost nothing, including the exchange fee.

Live gateway codes

Rows below are transcribed from sdks/consistency/fixtures/errors.json.

code	http	when it happens	source
`no_match`	404	no seller matched the bid	errors.json
`bid_timeout`	504	bid expired before a seller matched	errors.json
`request_timeout`	504	request timed out before a seller matched	errors.json
`rate_limited`	429	per-key rate limit exceeded	errors.json
`insufficient_balance`	402	account has insufficient pre-funded balance	errors.json
`seller_unreachable`	502	winning seller could not be reached	errors.json
`unauthorized`	401	missing or invalid credentials	errors.json
`forbidden`	403	caller is not allowed to perform the action	errors.json
`not_found`	404	resource does not exist	errors.json
`invalid_model`	400	requested model is not recognized	errors.json
`teapot`	418	unrecognized or uncategorized code	errors.json (`unknown_code`)

The last row is the SDK fallback when the gateway returns a code the client does not map.