Error Handling

All Ratio API errors follow a consistent JSON envelope with machine-readable codes for programmatic handling.

Error response format

{
  "success": false,
  "error": {
    "code": "CORRIDOR_NOT_AUTHORIZED",
    "message": "this partner credential is not authorized for the requested corridor",
    "corridor": null,
    "details": {}
  },
  "meta": {
    "request_id": "req_1789549205987654321",
    "timestamp": "2026-09-16T09:00:05Z"
  }
}

Field	Type	Description
`success`	boolean	Always `false` for error responses
`error.code`	string	Machine-readable error code — use this for programmatic handling
`error.message`	string	Human-readable description (do not parse — may change)
`error.corridor`	string or null	Reserved. Currently always `null`
`error.details`	object	Reserved for additional context. Currently `{}`
`meta.request_id`	string	Include in all support escalations

A few errors are returned as plain-text (non-JSON) bodies: 422 for a request body with the wrong shape, 415 for a POST without Content-Type: application/json, and 400 when the body is not valid JSON or the query string cannot be parsed. Gateway errors (e.g. missing auth headers) are JSON but have no meta. Always check Content-Type before parsing as JSON.

Error codes by endpoint

Quote errors (`POST /v1/quote`, `POST /v1/firm-quote`)

HTTP	Description
`400`	Invalid request — amount outside limits, tokens not in corridor, insufficient liquidity
`401`	Authentication failed (bad API key, signature mismatch, timestamp too old)
`403`	Corridor or `signer` wallet not enabled for your credential
`409`	Duplicate `client_ref` (firm quote only) or daily volume limit reached
`422`	Malformed request body (plain-text response)
`503`	Quoting temporarily unavailable — market data, risk state, or corridor halted

Execution lookup errors (`GET /v1/executions`)

HTTP	Description
`400`	Invalid query parameters, or lookup params combined with history filters
`401`	Authentication failed
`404`	Execution not found — may not be indexed yet, retry after a few seconds

Corridor and rate errors

HTTP	Description
`401`	Authentication failed
`503`	Corridor state or oracle price temporarily unavailable

Retry guidance

HTTP range	Action
400	Do not retry with the same parameters. Fix the request or request a new quote.
401	Check your API key, secret, timestamp (within 30s), and HMAC signature computation.
403	Your credential is not authorised for this corridor or wallet. Contact your account manager.
409	Use a different `client_ref` value (firm quote) or wait for the limit window to reset.
422	Check your JSON body — a field may be missing, the wrong type, or malformed.
429	Too many failed authentication attempts. Fix your signing, then retry after 60 seconds.
500 / 502	Retry with exponential backoff: 1s → 2s → 4s → 8s. Contact support if persistent.
503	Wait 5–30 seconds. Check `GET /v1/corridors` for corridor availability before retrying.

Best practices

Handle errors by HTTP status first; error.code provides more specific detail. New codes may be added at any time — handle unrecognised codes by their HTTP status.
Log meta.request_id for every error. This is essential for support escalation.
Check GET /v1/corridors proactively to see corridor state before sending quote requests.
A 404 on GET /v1/executions after 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-id and therefore a new HMAC signature.

Get Started

Features

Architecture

Integration

Partners

Resources

Error Handling

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

​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

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