Errors

{
  "error": {
    "code": "QUOTE_EXPIRED",
    "type": "CONFLICT",
    "message": "The quoted rate has expired. Request a new quote.",
    "retryStrategy": "FIX_AND_RESUBMIT",
    "details": {
      "quoteId": "qte_3FfGK34vwMvVFDedyb2nkf",
      "expiredAt": "2026-04-28T10:00:00.000Z"
    }
  }
}

​

Why this shape

1. No code. Clients have to string-match message, which breaks the moment a copy edit lands.
2. No trace ID. Triage starts with “send us your logs.”
3. No structure. “Insufficient balance” tells you what’s wrong, but not by how much, in which currency.

​

Error envelope fields

​

Triage matrix

​

Decision flow

​

HTTP status mapping

​

404 vs 403: when each fires

​

Code stability guarantee

​

Client error modeling

• An unknown error.type should be handled as INTERNAL_ERROR (treat it as a server-side category you don’t yet model).
• An unknown error.code should bubble up with its X-Trace-Id so a newly-added code never silently breaks your client.
• An unknown error.retryStrategy should be handled as TERMINAL (the safest default — don’t retry automatically).

​

Error code catalog

​

Handling errors: the catch-and-branch pattern

// Sign on every attempt — do not capture one. Two reasons:
//   1. JWT + signature freshness. JWTs have a 60s TTL and the X-Request-Signature
//      is bound to the JWT's nonce. A captured `Authorization` or `X-Request-Signature`
//      goes stale across any rate-limit wait that approaches the TTL; the next
//      attempt fails with `401 AUTH_TOKEN_EXPIRED`, or with `401 AUTH_TOKEN_INVALID`
//      (`details.reason: "SIGNATURE_INVALID"`) inside what looks like a rate-limit
//      retry. The signed nonce being replayed against Valkey would also surface as
//      `401 AUTH_TOKEN_INVALID` (`details.reason: "REPLAYED"`).
//   2. Body reuse. Request bodies are consumed by the first fetch(), so retrying
//      with the same Request object throws `TypeError: Body has already been read`.
//
// The caller passes `method`, `body`, an `extraHeaders` factory for things like
// `Idempotency-Key` that must stay stable across attempts, and `signRequest`.
// Each recursive retry signs fresh and rebuilds the `init`. See Rate limiting →
// Handling rate limits pattern (canonical reference):
// https://docs.openfx.com/v3/rate-limiting#handling-rate-limits-pattern
async function call(url, method, body, extraHeaders, signRequest) {
  const signed = signRequest({ method, url, body });
  const res = await fetch(url, {
    method,
    headers: { ...signed.headers, ...extraHeaders },
    body: signed.body,
  });
  const traceId = res.headers.get("x-trace-id"); // Capture FIRST: always present
  console.log({ url, trace_id: traceId, status: res.status });

  if (res.ok) return res.json();

  const { error } = await res.json();

  switch (error.code) {
    // Bespoke: quote stale, get a fresh one instead of a blind retry
    case "QUOTE_EXPIRED": {
      return refreshQuoteAndRetry(url, method, body, extraHeaders, signRequest);
    }

    // Bespoke: surface the structured balance shortfall to the user
    case "WITHDRAWAL_INSUFFICIENT_BALANCE": {
      const { requiredAmount, availableAmount, currency } = error.details;
      throw new Error(
        `${error.code}: required ${requiredAmount} ${currency}, available ${availableAmount} ${currency} (trace ${traceId})`,
      );
    }
  }

  // No code-specific override matched above — fall back to the
  // server-declared retryStrategy. This is where every future code lands
  // automatically, with no client-side code list to maintain.
  switch (error.retryStrategy) {
    // Retry immediately with the same Idempotency-Key.
    case "RETRY_SAME_KEY": {
      return call(url, method, body, extraHeaders, signRequest); // next attempt: fresh JWT + signature
    }

    // Wait, then retry with the same key. Transient backpressure — e.g.
    // RATE_LIMIT_EXCEEDED, IDEMPOTENCY_IN_FLIGHT, IDEMPOTENCY_UNAVAILABLE.
    // Retry-After (seconds, not an epoch timestamp) is present on
    // RATE_LIMIT_EXCEEDED and IDEMPOTENCY_IN_FLIGHT, but NOT on
    // IDEMPOTENCY_UNAVAILABLE — fall back to a fixed short wait when it's
    // absent. The wait can exceed the 60s JWT TTL — which is why `call`
    // signs per attempt.
    case "WAIT_THEN_RETRY_SAME_KEY": {
      const retryAfterHeader = res.headers.get("retry-after");
      const retryAfter =
        retryAfterHeader === null ? NaN : Number(retryAfterHeader);
      const waitMs = Number.isFinite(retryAfter) ? retryAfter * 1000 : 5000; // 5s fallback when Retry-After is absent
      await sleep(waitMs);
      return call(url, method, body, extraHeaders, signRequest); // next attempt: fresh JWT + signature
    }

    // FIX_AND_RESUBMIT, CHECK_STATE_THEN_RETRY, TERMINAL, and any future
    // unrecognized value: bubble up. The trace ID is always present for support.
    case "FIX_AND_RESUBMIT":
    case "CHECK_STATE_THEN_RETRY":
    case "TERMINAL":
    default:
      throw new Error(
        `API error: ${error.code} (${error.retryStrategy}) — ${error.message} (trace ${traceId})`,
      );
  }
}

// Usage:
//   const idempotencyKey = randomUUID();  // stable per logical operation
//   const body = JSON.stringify(payload);
//   await call(
//     'https://api.openfx.com/v3/fx/trades',
//     'POST',
//     body,
//     { 'Idempotency-Key': idempotencyKey },     // stable across attempts; merged after signed headers
//     signRequest,
//   );

​

Retrying trade execution failed

1. Call GET /v3/fx/trades/{id} with the resource ID returned by the original POST. If the trade exists, it EXECUTED; if you get 404 TRADE_NOT_FOUND, it didn’t.
2. If the trade exists: treat the operation as successful. Do not retry.
3. If the trade doesn’t exist: retry the original POST /v3/fx/trades with the same Idempotency-Key. The 24-hour TTL means the server still knows the key, so a duplicate cannot land. If the original quote has since expired, request a fresh quote first and use a new idempotency key for the new trade attempt.

​

Common mistakes

• Switching on message instead of code. message is human-readable and may be rephrased between releases. Only code is stable. The trade-up: lock your switch statement to codes the day you ship.
• Forgetting to read X-Trace-Id until something breaks. Capture it on every response (success too) and store it in the same log line as the request. Asking support to find a request without a trace ID adds hours to triage.
• Assuming HTTP status maps cleanly to error.type. Most do, but IDEMPOTENCY_MISMATCH returns 422 with type: "CONFLICT". Always branch on error.code for behavior; use type only for categorisation.
• Rebuilding a code-pattern list to decide retry behavior. error.retryStrategy already carries this — read it directly instead of maintaining your own mapping of codes to retry buckets. It also covers codes added after you shipped.
• Treating WITHDRAWAL_INSUFFICIENT_BALANCE as retryable. It’s a 409 (well-formed request, state-driven failure). Retrying without resolving the underlying balance hits the same error every time. Surface it to the user.
• Retrying a 500 trade failure with a fresh Idempotency-Key. A new key on TRADE_EXECUTION_FAILED risks executing the trade twice. The correct flow is the state-check-then-retry rule above: call GET /v3/fx/trades/{id} first; if the trade isn’t there, retry the original POST with the same key (still in-TTL for 24 h). See Idempotency.

​

Notable v2 → v3 changes

• Missing idempotency key returns 428 IDEMPOTENCY_KEY_MISSING, not v2’s 400 IDEMPOTENCY_KEY_REQUIRED (see v2 migration step 5). The other v2 idempotency codes carry over with the same statuses: 409 IDEMPOTENCY_IN_FLIGHT, 422 IDEMPOTENCY_MISMATCH.
• *_NOT_FOUND returns 404, not 400 (v2 returned 400)
• WITHDRAWAL_INSUFFICIENT_BALANCE is 409 conflict, not 400 (well-formed request, current state prevents it)
• Read-path 500s collapse into INTERNAL_ERROR. v2-style per-resource codes like TRADE_FETCH_FAILED, QUOTE_FETCH_FAILED, WITHDRAWAL_FETCH_FAILED, DEPOSIT_LIST_FAILED, BALANCE_FETCH_FAILED, and the inconsistent v2 MARKET_FETCH_FAILED all surface as 500 INTERNAL_ERROR in v3. Write-path 500s keep their domain codes (TRADE_EXECUTION_FAILED, WITHDRAWAL_INITIATION_FAILED) because those carry details.resourceId for the check-state-then-retry pattern.
• Only cataloged codes are part of the contract. The example does not define separate 502, 504, or 451 error codes. Documented domain failures use their cataloged codes; other server failures use 500 INTERNAL_ERROR.
• Withdrawal-account list filters exist (?assetType, ?network, ?currency, ?status, ?verified). Malformed filter values return the generic 400 VALIDATION_QUERY_FAILED — v2’s per-field filter-error codes (WALLET_FILTER_INVALID_COIN, WALLET_FILTER_INVALID_NETWORK) have no v3 successor. The v2 list-failure codes WALLET_LIST_FAILED / WALLET_FIAT_LIST_FAILED are absorbed into INTERNAL_ERROR along with the other read-path 500s.
• Validation errors carry details.issues[] (the Zod issue array), not a single message
• error.type is mandatory. v2’s hybrid envelope only guaranteed a message; v3 guarantees code, type, message, retryStrategy, and details on every error response (details is {} when empty). Clients migrating from v2 can switch on type for coarse routing without defensive null-checks.
• error.retryStrategy has no v2 equivalent. v2 clients had to infer retry behavior from code and HTTP status. v3 adds a direct, machine-readable recovery hint — see Triage matrix.

​

What’s next