Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ratiofx.com/llms.txt

Use this file to discover all available pages before exploring further.

All Ratio API errors follow a consistent JSON format with machine-readable codes for programmatic handling and human-readable messages for debugging.

​
Error response format

{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "Quote has expired; please re-request",
    "corridor": "USD-IDR",
    "timestamp": "2026-02-27T10:05:00Z",
    "request_id": "req_abc123"
  }
}
​
error.code
string
Machine-readable error code. Use this field for programmatic handling — do not parse message.
​
error.message
string
Human-readable description of the error.
​
error.corridor
string
Affected corridor, if applicable.
​
error.timestamp
string
ISO 8601 server timestamp.
​
error.request_id
string
Unique request identifier. Include this when contacting support.

​
FX Engine errors

These errors originate from the FX Engine and are specific to quote and execution operations.
HTTPCodeDescriptionResolution
400BELOW_MIN_TRANSACTION_SIZEAmount is below the minimum for this corridorIncrease amount to meet the corridor’s minimum transaction size
400DIRECTION_BLOCKEDTrade direction not permitted under current stateWait for state recovery or try the opposite direction
400ARB_CHECK_FAILEDQuote failed internal arbitrage validationRe-request — market conditions may have shifted
400QUOTE_EXPIREDFirm quote has expiredRequest a new firm quote at current rates
422NO_VIABLE_RFQ_QUOTENo acceptable external quote availableRetry with a smaller size or wait for liquidity to improve
422CROSS_LEG_INSUFFICIENTInsufficient liquidity for cross-corridor executionRetry with a smaller size
503ORACLE_STALEOracle price data is outdatedWait for oracle recovery (typically seconds)
503ORACLE_DEVIATIONOracle sources diverge beyond thresholdWait for oracle convergence
503QUOTE_HALTEDSystem is in HALT state — no new quotesWait for system recovery; monitor GET /v1/system/state

​
General API errors

HTTPCodeDescriptionResolution
401UNAUTHORIZEDMissing or invalid Bearer tokenCheck your API key
403FORBIDDENValid token but insufficient permissionsRequest the appropriate access scope from your account manager
404NOT_FOUNDResource does not existVerify the corridor name, quote ID, or endpoint path
429RATE_LIMITEDToo many requestsImplement exponential backoff; respect the Retry-After header
500INTERNAL_ERRORUnexpected server errorRetry after a short delay; contact support if errors persist

​
Retry guidance

HTTP rangeCategoryRecommended action
400Client error or timing issueFix the request parameters or request a fresh quote. Do not retry the same request.
422Liquidity or size constraintReduce trade size, try a different corridor, or wait for liquidity to improve.
429Rate limitWait for the duration specified in the Retry-After header, then retry.
500Server errorRetry with exponential backoff (1s → 2s → 4s → 8s). Contact support if errors persist.
503System-level issueWait 5–30 seconds and retry. Check GET /v1/system/state for corridor availability.
Never retry 400 errors with the same parameters. They indicate a client-side issue that must be corrected before retrying.

​
Best practices

  • Always check error.code for programmatic handling. Do not parse the message string — it is intended for human debugging only and may change.
  • Log error.request_id for every error response. This is essential for support escalation.
  • Monitor GET /v1/system/state proactively rather than waiting for 503 errors. This lets you disable corridors in your UI before users encounter failures.
  • Implement graceful degradation. When a corridor enters a protective state, show users a clear message rather than exposing raw error codes.
  • Use exponential backoff for 500 and 503 retries to avoid overwhelming the system during recovery.