Error Handling

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"
  }
}

string

Machine-readable error code. Use this field for programmatic handling — do not parse message.

string

Human-readable description of the error.

string

Affected corridor, if applicable.

string

ISO 8601 server timestamp.

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.

HTTP	Code	Description	Resolution
`400`	`BELOW_MIN_TRANSACTION_SIZE`	Amount is below the minimum for this corridor	Increase amount to meet the corridor’s minimum transaction size
`400`	`DIRECTION_BLOCKED`	Trade direction not permitted under current state	Wait for state recovery or try the opposite direction
`400`	`ARB_CHECK_FAILED`	Quote failed internal arbitrage validation	Re-request — market conditions may have shifted
`400`	`QUOTE_EXPIRED`	Firm quote has expired	Request a new firm quote at current rates
`422`	`NO_VIABLE_RFQ_QUOTE`	No acceptable external quote available	Retry with a smaller size or wait for liquidity to improve
`422`	`CROSS_LEG_INSUFFICIENT`	Insufficient liquidity for cross-corridor execution	Retry with a smaller size
`503`	`ORACLE_STALE`	Oracle price data is outdated	Wait for oracle recovery (typically seconds)
`503`	`ORACLE_DEVIATION`	Oracle sources diverge beyond threshold	Wait for oracle convergence
`503`	`QUOTE_HALTED`	System is in HALT state — no new quotes	Wait for system recovery; monitor `GET /v1/system/state`

General API errors

HTTP	Code	Description	Resolution
`401`	`UNAUTHORIZED`	Missing or invalid Bearer token	Check your API key
`403`	`FORBIDDEN`	Valid token but insufficient permissions	Request the appropriate access scope from your account manager
`404`	`NOT_FOUND`	Resource does not exist	Verify the corridor name, quote ID, or endpoint path
`429`	`RATE_LIMITED`	Too many requests	Implement exponential backoff; respect the `Retry-After` header
`500`	`INTERNAL_ERROR`	Unexpected server error	Retry after a short delay; contact support if errors persist

Retry guidance

HTTP range	Category	Recommended action
400	Client error or timing issue	Fix the request parameters or request a fresh quote. Do not retry the same request.
422	Liquidity or size constraint	Reduce trade size, try a different corridor, or wait for liquidity to improve.
429	Rate limit	Wait for the duration specified in the `Retry-After` header, then retry.
500	Server error	Retry with exponential backoff (1s → 2s → 4s → 8s). Contact support if errors persist.
503	System-level issue	Wait 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.

Get Started

Features

Architecture

Integration

Partners

Resources

Error Handling

Error response format

FX Engine errors

General API errors

Retry guidance

Best practices

​Error response format

​FX Engine errors

​General API errors

​Retry guidance

​Best practices

Error response format

FX Engine errors

General API errors

Retry guidance

Best practices