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

// Sign on every attempt. Do not capture one. JWTs have a 60s TTL and the
// X-Request-Signature is bound to the JWT's nonce, so a captured pair goes
// stale across any wait that approaches the TTL (next attempt fails with
// `401 AUTH_TOKEN_EXPIRED` or `401 AUTH_TOKEN_INVALID`). Request bodies are
// also consumed by the first fetch(), so retrying the same Request object
// throws `TypeError: Body has already been read`.
//
// The caller passes `method`, `body`, an `extraHeaders` object 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,
  attempt = 0,
  maxAttempts = 5,
) {
  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": {
      if (attempt + 1 >= maxAttempts) {
        throw new Error(
          `Retry budget exhausted: ${error.code} (trace ${traceId})`,
        );
      }
      return call(
        url,
        method,
        body,
        extraHeaders,
        signRequest,
        attempt + 1,
      ); // next attempt: fresh JWT + signature
    }

    // Transient backpressure. See the Triage matrix above for which codes
    // carry Retry-After. Falls back to a fixed short wait when it's absent.
    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
      if (attempt + 1 >= maxAttempts) {
        throw new Error(
          `Retry budget exhausted: ${error.code} (trace ${traceId})`,
        );
      }
      await sleep(waitMs);
      return call(
        url,
        method,
        body,
        extraHeaders,
        signRequest,
        attempt + 1,
      ); // 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,
//   );