Status Codes & Error Handling

HTTP status codes, the error body, and endpoint-specific conditions for the Conversion API.

Error Object

Errors follow the platform-wide RFC 7807 style body. The code field is the stable application error code; see Error Codes for the full list.

{
  "code": "00020001",
  "status": 400,
  "detail": "Quote has expired",
  "instance": "/v1/customers/14f20ebd-893b-11f0-b308-2eaa4f6974f2/conversions/hedge",
  "trace_id": "d49d5864-49f0-4130-96ba-6a3c0cfa85a0",
  "time": "2026-02-05T10:08:07.857Z"
}

Field	Type	Description
`code`	string	Stable application error code.
`status`	integer	HTTP status code.
`detail`	string	Human-readable description. May be null.
`issues`	array	Optional structured issue details, when provided.
`instance`	string	Request path. May be null.
`trace_id`	string	Trace identifier. Include it in support requests.
`time`	string	ISO 8601 timestamp of the error.

Conversion Error Codes

Any guidance below to request or execute a new quote applies only when there is no earlier Execute Quote request with an unknown outcome. Otherwise, first follow Resolving an Execute Quote timeout; an error response to a later request does not resolve the earlier operation.

`code`	HTTP	When
`00020000`	408	Quote request timed out; the liquidity provider did not respond. Retry the quote.
`00020001`	400	Quote expired. Request a replacement only if no earlier execution has an unresolved outcome.
`00020002`	400	Quote construction or pricing failed.
`00020003`	400	Insufficient available balance in the pay asset.
`00020004`	400	Pair is disabled for this direction, or the amount is outside the pair's min/max.
`00020005`	400	Pricing changed. Re-quote and execute only if no earlier execution has an unresolved outcome.
`00020006`	400	Generic trading error.
`00000001`	400	Business rule validation failed (for example both or neither amount supplied).
`00000002`	400	Invalid payload or parameters.
`00000005`	404	Conversion not found for the supplied `transaction_id`.
`00000006`	409	Quote has already been consumed. This does not confirm that an order was created or completed.
`00000010`	400	Invalid request format (for example a `quote_id` that is not a UUID).

Create Quote — Status & Errors

Endpoint: POST /v1/customers/{customer_id}/conversions/quote

HTTP	Example `code`	When
201	—	Quote priced successfully
400	`00000001`, `00000002`, `00020004`	Both amounts supplied or neither; unsupported asset; amount out of bounds
400	`00020002`, `00020005`	Pricing failed or must be re-requested
401	`00010000`	Missing or invalid authentication
405	—	Wrong HTTP method for the path
408	`00020000`	Liquidity provider did not respond in time
500	`00000000`	Unexpected server error

Execute Quote — Status & Errors

Endpoint: POST /v1/customers/{customer_id}/conversions/hedge

HTTP	Example `code`	When
201	—	Conversion order created; `order_status` is `PENDING`
400	`00000010`	`quote_id` is not a valid UUID
400	`00020001`	Quote expired, unknown, or does not belong to this customer
400	`00020003`	Insufficient available balance in the pay asset
401	`00010000`	Missing or invalid authentication
405	—	Wrong HTTP method for the path
409	`00000006`	Quote has already been consumed; order creation or completion is not confirmed
500	`00000000`	Unexpected server error

Get Conversion — Status & Errors

Endpoint: GET /v1/customers/{customer_id}/conversions/order?transaction_id={transaction_id}

HTTP	Example `code`	When
200	—	Conversion returned
400	`00000002`	Missing or malformed `transaction_id`
401	`00010000`	Missing or invalid authentication
404	`00000005`	No conversion with that `transaction_id` exists for this customer
405	—	Wrong HTTP method for the path
500	`00000000`	Unexpected server error

A conversion belonging to another customer is reported as 404, not 403.

Idempotency, Retries & Timeouts

Execute Quote does not accept an Idempotency-Key header. Retrying is controlled by the quote instead: a quote_id is single-use and expires after 30 seconds.

Topic	Guidance
Idempotency key	Not supported on any conversion endpoint. Do not send `Idempotency-Key`; it has no effect.
Retrying Execute Quote	Treat an interrupted execution as outcome unknown. Reconcile it before deciding whether another conversion is needed.
Client timeout on execute	The request may still be running or may have created an order. Do not submit a replacement conversion while its outcome is unknown.
Quote lifetime	30 seconds (`expire_time`, `valid_until_timestamp`). Expiry prevents a new execution of that quote; it does not resolve an earlier execution's outcome.
Retrying reads	Get Conversion and List Transactions are safe to retry with exponential backoff (for example 200 ms → 400 ms → 800 ms, with jitter).
Trace IDs	Log `trace_id` from error responses for support correlation.

Resolving an Execute Quote timeout

If Execute Quote times out before you receive a transaction_id, keep the operation in an outcome unknown state:

Record the customer, quote_id, request time, assets, amounts, and any available trace_id.
Use List Transactions with transaction_action=CONVERSION and a time window around the request (created_after and created_before). Include a margin for clock differences and inspect all pages. The list has no quote_id filter and its items do not contain quote_id.
For candidate transactions, call Get Conversion with their transaction_id and compare the returned quote_id. If it matches, the order exists; track its order_status and the conversion.completed / conversion.failed webhook to determine the outcome. Finding an order does not by itself mean the conversion completed.
If no match is found, retry the read-only reconciliation with backoff. An empty list can precede the original request's commit and does not prove that nothing executed. If you still cannot resolve the outcome, contact support with the recorded identifiers and request time.

Do not create and execute a replacement quote while the original outcome is unknown. Different quotes do not share an economic-operation idempotency key and could both execute. Only decide whether to initiate another conversion after the original operation has been reconciled.

A consumed or expired quote, a 409 response, or the absence of an order in one query does not establish the original operation's final outcome. The current API does not provide a direct quote-to-order lookup; use the reconciliation steps above rather than treating one of these signals as permission to start over.