Errors

CashXChain uses standard HTTP status codes and structured JSON error responses.

Error format

{
  "error": {
    "code": "quote_expired",
    "message": "The selected FX quote has expired.",
    "request_id": "req_7xY...",
    "details": {
      "quote_id": "fxq_9Xc2..."
    }
  }
}

HTTP status codes

HTTP	Meaning
400	Invalid request.
401	Authentication failed.
403	Permission or product access denied.
404	Resource not found.
409	Conflict, duplicate, or invalid state transition.
422	Request is valid JSON but cannot be processed.
429	Rate limit exceeded.
500	Internal error.
503	Temporary service or partner unavailable.

Common error codes

Code	Meaning
invalid_request	Request body or parameters are invalid.
authentication_required	Missing API key.
invalid_api_key	API key is invalid or revoked.
insufficient_scope	API key lacks required scope.
resource_not_found	Resource does not exist or is not accessible.
quote_expired	FX quote is no longer valid.
corridor_unavailable	Currency or country route is not enabled.
account_not_active	Account cannot transact.
beneficiary_not_active	Beneficiary cannot receive payments.
requires_action	Additional information or approval is required.
idempotency_conflict	Same idempotency key used with different body.
partner_unavailable	Downstream partner is temporarily unavailable.
rate_limit_exceeded	Too many requests.

Request IDs

Every error includes a request ID where possible. Include this ID when contacting support.

Safe retries

Payment creation should always include an idempotency key. This makes network retries safe.