Error response format
Error codes by endpoint
Quote errors (POST /v1/quote, POST /v1/firm-quote)
Execution lookup errors (GET /v1/executions)
Corridor and rate errors
Retry guidance
Best practices
- Handle errors by HTTP status first;
error.codeprovides more specific detail. New codes may be added at any time — handle unrecognised codes by their HTTP status. - Log
meta.request_idfor every error. This is essential for support escalation. - Check
GET /v1/corridorsproactively to see corridor state before sending quote requests. - A
404onGET /v1/executionsafter an on-chain transaction usually means the indexer hasn’t caught up — retry in 3–5 seconds, not an actual missing execution. - Every retry of a POST request needs a new
x-ratio-request-idand therefore a new HMAC signature.