Unified Error Code Reference

This page consolidates all error codes, rejection codes, and HTTP error responses across the Ratio FX system. Partners should use this as the primary reference for building error handling, retry logic, and user-facing messages.

FX Engine — Rejection Codes

These codes are returned when the FX Engine rejects a quote or execu request. Each code maps to a specific pipeline layer.

HTTP	Code	Message	Layer	Cause	Retry?
400	DIRECTION_BLOCKED	Trade direction not permitted under current state	Layer 2	RESTRICT state active; only one direction allowed for this corridor	Wait for state recovery or try opposite direction
422	NO_VIABLE_RFQ_QUOTE	External RFQ returned no acceptable quote	Layer 3	Size exceeds Active Pool depth and no external MM quote within acceptable deviation band	Retry with smaller size or wait for liquidity
422	CROSS_LEG_INSUFFICIENT	Insufficient liquidity for cross-route execution	Layer 4	One or both legs of MYR-IDR cross route lack sufficient Active Pool depth	Retry with smaller size or use direct corridor
503	ORACLE_STALE	Oracle price data is outdated	Layer 5	Freshness threshold breached; state set to HALT	Wait for oracle recovery (typically seconds)
503	ORACLE_DEVIATION	Oracle sources diverge beyond acceptable threshold	Layer 5	Pyth and Orakl rates deviate beyond configured corridor maximum	Wait for oracle convergence
503	QUOTE_HALTED	System is in HALT state; no new quotes	Layer 6	Severe volatility or oracle failure has triggered HALT	Wait for system recovery; monitor /v1/system/state
400	BELOW_MIN_TRANSACTION_SIZE	Transaction amount is below the minimum for this corridor	Layer 1	Amount less than smallest fee tier min_amount	Increase amount to meet corridor minimum
400	ARB_CHECK_FAILED	Quote failed arbitrage validation	Layer 8	One of three arb checks failed: internal consistency, synthetic gap, or triangular loop	Re-request; market conditions may have shifted
400	QUOTE_EXPIRED	Quote has expired; please re-request	Layer 9	Execution attempted after quote expiry timestamp	Re-request a fresh quote

Retry Guidance

HTTP Code	Category	Recommended Action
400	Client-side or timing issue	Re-request with corrected parameters or fresh quote
422	Liquidity or size constraint	Reduce trade size, try different corridor, or wait for liquidity
503	System-level issue	Wait and retry after 5–30 seconds; check system state endpoint

Reserve Pool VaR — API Error Codes

These codes are returned by the Reserve Pool risk management endpoints (/v1/reserve/*).

HTTP	Code	Description	Resolution
403	INSUFFICIENT_SCOPE	Emergency RFQ and state override endpoints require ops-level authentication scope	Use ops-level bearer token
409	EMERGENCY_RFQ_IN_PROGRESS	An Emergency RFQ is already in progress for this corridor	Wait for current Emergency RFQ resolution before triggering another
422	CORRIDOR_HALTED	Corridor is in HALT state	Manual intervention required before any automated actions can proceed
422	BELOW_MIN_LIQUIDITY	Reserve Pool is below minimum liquidity threshold	Cannot execute rebalance that would further reduce USDT balance

General API Errors

These apply across all Ratio FX endpoints.

HTTP	Code	Description	Resolution
401	UNAUTHORIZED	Missing or invalid Bearer token	Check authentication credentials
403	FORBIDDEN	Valid token but insufficient permissions for this endpoint	Request appropriate access scope
404	NOT_FOUND	Requested resource does not exist	Verify corridor name, batch ID, or endpoint path
429	RATE_LIMITED	Too many requests	Implement exponential backoff; respect Retry-After header
500	INTERNAL_ERROR	Unexpected server error	Retry after delay; contact support if persistent

Error Response Format

All error responses follow a consistent JSON structure:

{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "Quote has expired; please re-request",
    "layer": "Layer 9",
    "corridor": "USD-IDR",
    "timestamp": "2026-02-27T10:05:00Z",
    "request_id": "req_abc123"
  }
}

Field	Type	Description
code	string	Machine-readable error code (use for programmatic handling)
message	string	Human-readable description
layer	string	Pipeline layer where the error originated (FX Engine errors only)
corridor	string	Affected corridor, if applicable
timestamp	ISO 8601	Server timestamp of the error
request_id	string	Unique request identifier for support escalation