@huskly/ibkr-client 0.29.0 → 1.1.0

package/dist/ibkr/ibkrClient.js

@@ -81,16 +81,17 @@ function extractOsiPositionSymbol(contractDescription) {
     return /\[([A-Z]+\s*\d{6}[CP]\d{8})\s+\d+\]\s*$/.exec(contractDescription)?.[1];
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-function parseRetryAfter(raw) {
+function parseRetryAfter(raw, now) {
     const asString = typeof raw === "string" ? raw.trim() : undefined;
     if (!asString)
         return undefined;
     const numeric = Number(asString);
-    if (Number.isFinite(numeric) && numeric > 0)
-        return Math.ceil(numeric * 1000);
+    const numericMs = Math.ceil(numeric * 1000);
+    if (Number.isSafeInteger(numericMs) && numericMs > 0)
+        return numericMs;
     const date = Date.parse(asString);
     if (!Number.isNaN(date)) {
-        const ms = Math.max(0, date - Date.now());
+        const ms = Math.max(0, date - now);
         if (ms > 0)
             return ms;
     }
@@ -99,6 +100,25 @@ function parseRetryAfter(raw) {
 function isUnknownRecord(input) {
     return typeof input === "object" && input !== null && !Array.isArray(input);
 }
+const PRICE_HISTORY_SECURITY_TYPES = new Set([
+    "STK",
+    "IND",
+    "OPT",
+    "FUT",
+    "FOP",
+    "CASH",
+    "CFD",
+    "WAR",
+    "FUND",
+    "BOND",
+    "CMDTY",
+]);
+function isPriceHistorySecurityType(value) {
+    return PRICE_HISTORY_SECURITY_TYPES.has(value);
+}
+function isFiniteHistoryBar(bar) {
+    return [bar.t, bar.o, bar.h, bar.l, bar.c, bar.v].every((value) => typeof value === "number" && Number.isFinite(value));
+}
 function isHeadersLike(input) {
     return (typeof input === "object" &&
         input !== null &&
@@ -168,6 +188,60 @@ function monthCodes(fromDate, toDate) {
     }
     return result;
 }
+/** A typed HTTP failure from the IBKR transport. */
+export class IbkrHttpError extends Error {
+    status;
+    response;
+    statusCode;
+    constructor(message, status, response, options) {
+        super(message, options);
+        this.status = status;
+        this.response = response;
+        this.name = "IbkrHttpError";
+        this.statusCode = status;
+    }
+}
+/**
+ * Typed broker rejection for documented IBKR error-object payloads outside order
+ * submission result envelopes. Callers can catch this class to read the retained
+ * {@link BrokerErrorDetail} without parsing free-form message text.
+ */
+export class IbkrBrokerResponseError extends Error {
+    detail;
+    constructor(message, detail, options) {
+        super(message, options);
+        this.detail = detail;
+        this.name = "IbkrBrokerResponseError";
+    }
+}
+/** Typed contract-resolution failure raised before a price-history broker request. */
+export class IbkrPriceHistoryContractError extends Error {
+    code;
+    candidates;
+    constructor(message, code, candidates = []) {
+        super(message);
+        this.code = code;
+        this.candidates = candidates;
+        this.name = "IbkrPriceHistoryContractError";
+    }
+}
+/** A daily history request for which IBKR did not return the full requested interval. */
+export class IbkrInsufficientHistoryError extends Error {
+    symbol;
+    requestedStart;
+    requestedEnd;
+    availableStart;
+    availableEnd;
+    constructor(symbol, requestedStart, requestedEnd, availableStart, availableEnd, options) {
+        super(`IBKR returned insufficient daily history for ${symbol}`, options);
+        this.symbol = symbol;
+        this.requestedStart = requestedStart;
+        this.requestedEnd = requestedEnd;
+        this.availableStart = availableStart;
+        this.availableEnd = availableEnd;
+        this.name = "IbkrInsufficientHistoryError";
+    }
+}
 /**
  * Typed IBKR Web API client implementing the broker-neutral {@link BrokerClient}.
  * Wraps the `ibkr-client` npm package, which performs the OAuth 1.0a
@@ -179,17 +253,26 @@ export class IbkrClient {
     initPromise;
     accountIdPromise;
     optionDiscovery = new Map();
-    optionUnderlyingDiscovery = new Map();
     optionContractResolution = new Map();
     derivativeDiscovery = new Map();
     requestScheduler;
+    requestNow;
+    secdefPrimingTail = Promise.resolve();
+    onPriceHistoryTelemetry;
+    onOptionDiscoveryTelemetry;
+    onRequestTelemetry;
     constructor(config, options = {}) {
         this.raw = new RawIbkrClientCtor(config);
+        this.onPriceHistoryTelemetry = options.onPriceHistoryTelemetry ?? (() => undefined);
+        this.onOptionDiscoveryTelemetry = options.onOptionDiscoveryTelemetry ?? (() => undefined);
+        this.onRequestTelemetry = options.onRequestTelemetry ?? (() => undefined);
+        const schedulerOptions = options.requestScheduler;
+        this.requestNow = schedulerOptions?.now ?? (() => this.now());
         this.requestScheduler = new IbkrRequestScheduler({
-            ...options.requestScheduler,
-            now: () => this.now(),
-            sleep: (ms) => this.wait(ms),
-            random: () => this.random(),
+            ...schedulerOptions,
+            now: this.requestNow,
+            sleep: schedulerOptions?.sleep ?? ((ms) => this.wait(ms)),
+            random: schedulerOptions?.random ?? (() => this.random()),
             classifyError: (error) => this.classifyRequestError(error),
             ...(options.onRequestTelemetry === undefined
                 ? {}
@@ -199,7 +282,12 @@ export class IbkrClient {
     /** Obtain the live session token (idempotent — safe to await repeatedly). */
     init() {
         this.initPromise ??= (async () => {
-            await this.raw.init();
+            try {
+                await this.raw.init();
+            }
+            catch (error) {
+                throw this.normalizeHttpError(error);
+            }
             // IBKR is slow right after init; give the session a moment to settle.
             await this.wait(1000);
         })();
@@ -250,7 +338,7 @@ export class IbkrClient {
             path: "iserver/marketdata/snapshot",
             params: { conids, fields: "6509" },
         });
-        const response = await this.req({
+        const response = await this.singleAttemptRequest({
             path: `iserver/account/${request.accountId}/orders/whatif`,
             method: "POST",
             data: {
@@ -1336,7 +1424,7 @@ export class IbkrClient {
             openProfitLoss: toNumber(p.unrealizedPnl),
         };
     }
-    async getQuotes(requests) {
+    async getQuotes(requests, options = {}) {
         const unique = new Map();
         for (const request of requests) {
             if (!request.symbol.trim())
@@ -1363,9 +1451,9 @@ export class IbkrClient {
                 conid,
             };
         }));
-        return this.fetchQuotes(contracts.filter((contract) => contract !== undefined));
+        return this.fetchQuotes(contracts.filter((contract) => contract !== undefined), options.includeHistory ?? true);
     }
-    async fetchQuotes(contracts) {
+    async fetchQuotes(contracts, includeHistory) {
         if (!contracts.length)
             return {};
         const conids = contracts.map((contract) => contract.conid).join(",");
@@ -1379,7 +1467,9 @@ export class IbkrClient {
         const snapshotByConid = new Map(snapshots
             .filter((snapshot) => snapshot.conid !== undefined)
             .map((snapshot) => [snapshot.conid, snapshot]));
-        const histories = await Promise.all(contracts.map((contract) => this.fetchQuoteHistory(contract.conid)));
+        const histories = includeHistory
+            ? await Promise.all(contracts.map((contract) => this.fetchQuoteHistory(contract.conid)))
+            : contracts.map(() => undefined);
         const quotes = {};
         for (const [index, contract] of contracts.entries()) {
             const snapshot = snapshotByConid.get(contract.conid);
@@ -2248,7 +2338,7 @@ export class IbkrClient {
         }
         return "IBKR returned mixed or incomplete order evidence";
     }
-    normalizeBrokerError(error, response) {
+    normalizeBrokerError(error, response, defaultMessage = "IBKR rejected the order") {
         const nested = typeof error === "object" && error !== null ? error : undefined;
         const nestedMessage = nested ? nested.message : undefined;
         const responseMessage = response["message"];
@@ -2259,7 +2349,7 @@ export class IbkrClient {
             (typeof responseMessage === "string" && responseMessage.trim()) ||
             (typeof responseText === "string" && responseText.trim()) ||
             (typeof responseWarningMessage === "string" && responseWarningMessage.trim()) ||
-            "IBKR rejected the order";
+            defaultMessage;
         const nestedCode = nested ? nested.code : undefined;
         const responseCode = response["code"];
         const codeValue = nestedCode ?? responseCode;
@@ -2271,6 +2361,36 @@ export class IbkrClient {
             details: response,
         };
     }
+    /**
+     * Validate `iserver/secdef/search` at one shared boundary.
+     * Accept the documented success array, convert the documented error object into a typed
+     * broker error, and fail closed on any other shape. Never treat an error object as an empty
+     * successful search.
+     */
+    parseSecdefSearchResponse(response) {
+        if (Array.isArray(response)) {
+            return response;
+        }
+        if (isUnknownRecord(response) &&
+            response["error"] !== undefined &&
+            response["error"] !== null) {
+            // Any non-null `error` field is the documented IBKR error-object shape for this
+            // endpoint. Do not reclassify it as a malformed payload when the message is empty.
+            const detail = this.normalizeBrokerError(response["error"], response, "IBKR rejected the security-definition search");
+            throw new IbkrBrokerResponseError(detail.message, detail);
+        }
+        throw new Error("IBKR returned a malformed secdef/search response");
+    }
+    /** Serialize IBKR operations that mutate and then consume session security-definition state. */
+    withSecdefPriming(operation) {
+        const result = this.secdefPrimingTail.then(operation);
+        this.secdefPrimingTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /** Run one state-mutating search outside a larger priming transaction. */
+    searchSecdef(params) {
+        return this.withSecdefPriming(async () => this.parseSecdefSearchResponse(await this.req({ path: "iserver/secdef/search", params })));
+    }
     isMeaningfulBrokerError(error, response) {
         const nested = typeof error === "object" && error !== null ? error : undefined;
         const nestedRecord = nested;
@@ -2834,7 +2954,7 @@ export class IbkrClient {
         if (brokerageAccounts.accounts && !brokerageAccounts.accounts.includes(accountId)) {
             throw new Error(`IBKR account ${accountId} is not available for trading/order queries.`);
         }
-        const switchedAccount = await this.req({
+        const switchedAccount = await this.singleAttemptRequest({
             path: "iserver/account",
             method: "POST",
             data: { acctId: accountId },
@@ -2900,10 +3020,7 @@ export class IbkrClient {
         }
         // `trsrv/stocks` is equity/ETF-only. Fall back to security-definition search so
         // non-stock roots (indexes like VIX, futures, etc.) still resolve to a conid.
-        const search = await this.req({
-            path: "iserver/secdef/search",
-            params: { symbol: symbol.trim().toUpperCase() },
-        });
+        const search = await this.searchSecdef({ symbol: symbol.trim().toUpperCase() });
         const candidate = search.find((item) => item.conid !== undefined &&
             item.sections?.some((section) => {
                 const secType = section.secType?.trim().toUpperCase();
@@ -2920,32 +3037,136 @@ export class IbkrClient {
             conid: fallbackConid,
         };
     }
-    /** Return normalized daily price history without consulting a vendor-owned clock. */
+    /** Return complete daily history with the exact validated IBKR request context. */
     async getPriceHistory(input) {
-        const contract = await this.resolveQuoteContract(input.symbol);
-        if (!contract)
-            throw new Error(`IBKR could not resolve market-data contract: ${input.symbol}`);
-        const days = this.historyDays(input);
-        const history = await this.fetchQuoteHistory(contract.conid, `${String(days)}d`, false);
-        const volumeFactor = history?.volumeFactor ?? 1;
-        return (history?.data ?? []).map((bar) => {
-            if (bar.t === undefined ||
-                bar.o === undefined ||
-                bar.h === undefined ||
-                bar.l === undefined ||
-                bar.c === undefined ||
-                bar.v === undefined) {
-                throw new Error(`IBKR returned an incomplete history bar for ${input.symbol}`);
+        const requestedSymbol = input.symbol.trim().toUpperCase();
+        if (!requestedSymbol) {
+            throw new IbkrPriceHistoryContractError("Price history requires a symbol", "CONTRACT_INVALID");
+        }
+        const interval = this.historyInterval(input);
+        const period = `${String(interval.days)}d`;
+        const contract = await this.resolvePriceHistoryContract(requestedSymbol, input.contract);
+        const request = {
+            period,
+            ...(input.endDate === undefined ? {} : { startTime: this.historyStartTime(interval.end) }),
+        };
+        let bars;
+        try {
+            const history = await this.requestPriceHistory(contract, requestedSymbol, request);
+            bars = this.normalizeHistoryResponse(requestedSymbol, history, interval);
+            this.assertHistoryCoverage(requestedSymbol, bars, interval);
+        }
+        catch (error) {
+            if (!this.isChartDataUnavailable(error))
+                throw error;
+            bars = await this.recoverDailyHistory(contract, requestedSymbol, interval, error);
+        }
+        return {
+            bars,
+            contract,
+            request: { requestedSymbol, period, barSize: "1d" },
+        };
+    }
+    async resolvePriceHistoryContract(requestedSymbol, selector) {
+        if (selector !== undefined) {
+            if (!Number.isSafeInteger(selector.conid) || selector.conid <= 0) {
+                throw new IbkrPriceHistoryContractError(`Invalid IBKR price-history conid: ${String(selector.conid)}`, "CONTRACT_INVALID");
             }
-            return {
-                datetime: bar.t,
-                open: bar.o,
-                high: bar.h,
-                low: bar.l,
-                close: bar.c,
-                volume: bar.v * volumeFactor,
-            };
+            const expectedSecurityType = selector.assetClass?.trim().toUpperCase();
+            if (expectedSecurityType !== undefined && !isPriceHistorySecurityType(expectedSecurityType)) {
+                throw new IbkrPriceHistoryContractError(`Invalid IBKR price-history asset class: ${expectedSecurityType}`, "CONTRACT_INVALID");
+            }
+            return this.validatePriceHistoryContract(requestedSymbol, selector.conid, {
+                ...(expectedSecurityType === undefined ? {} : { securityType: expectedSecurityType }),
+                ...(selector.exchange === undefined
+                    ? {}
+                    : { exchange: selector.exchange.trim().toUpperCase() }),
+            });
+        }
+        const search = await this.searchSecdef({ symbol: requestedSymbol });
+        const candidates = search.flatMap((item) => {
+            const symbol = item.symbol?.trim().toUpperCase();
+            const conid = Number(item.conid);
+            if (symbol !== requestedSymbol ||
+                !Number.isSafeInteger(conid) ||
+                conid <= 0 ||
+                !Array.isArray(item.sections)) {
+                return [];
+            }
+            return item.sections.flatMap((section) => {
+                const securityType = section.secType?.trim().toUpperCase();
+                if (securityType !== "STK" && securityType !== "IND")
+                    return [];
+                const exchange = section.exchange?.trim().toUpperCase();
+                return [
+                    {
+                        conid,
+                        symbol,
+                        securityType,
+                        ...(exchange ? { exchange } : {}),
+                    },
+                ];
+            });
+        });
+        const uniqueCandidates = [
+            ...new Map([...candidates]
+                .sort((left, right) => (left.exchange ?? "").localeCompare(right.exchange ?? ""))
+                .map((candidate) => [[candidate.conid, candidate.securityType].join(":"), candidate])).values(),
+        ];
+        if (uniqueCandidates.length === 0) {
+            throw new IbkrPriceHistoryContractError(`IBKR returned no STK or IND contract for ${requestedSymbol}`, "CONTRACT_NOT_FOUND");
+        }
+        if (uniqueCandidates.length !== 1) {
+            const safeCandidates = uniqueCandidates.map((candidate) => ({
+                conid: candidate.conid,
+                symbol: candidate.symbol,
+                securityType: candidate.securityType,
+                exchange: candidate.exchange ?? null,
+            }));
+            throw new IbkrPriceHistoryContractError(`IBKR price-history contract is ambiguous for ${requestedSymbol}; specify contract.conid`, "CONTRACT_AMBIGUOUS", safeCandidates);
+        }
+        const candidate = uniqueCandidates[0];
+        if (candidate === undefined) {
+            throw new Error("IBKR price-history resolution lost its selected contract");
+        }
+        return this.validatePriceHistoryContract(requestedSymbol, candidate.conid, {
+            securityType: candidate.securityType,
+        });
+    }
+    async validatePriceHistoryContract(requestedSymbol, conid, expected) {
+        const response = await this.req({
+            path: `iserver/contract/${String(conid)}/info`,
         });
+        if (isUnknownRecord(response) &&
+            response["error"] !== undefined &&
+            response["error"] !== null) {
+            const detail = this.normalizeBrokerError(response["error"], response, "IBKR rejected the contract metadata request");
+            throw new IbkrBrokerResponseError(detail.message, detail);
+        }
+        if (!isUnknownRecord(response)) {
+            throw new IbkrPriceHistoryContractError(`IBKR returned malformed contract metadata for conid ${String(conid)}`, "CONTRACT_INVALID");
+        }
+        const info = response;
+        const returnedConid = Number(info.con_id);
+        const symbol = info.local_symbol?.trim().toUpperCase();
+        const securityType = info.instrument_type?.trim().toUpperCase();
+        const exchange = info.exchange?.trim().toUpperCase();
+        if (returnedConid !== conid ||
+            symbol === undefined ||
+            !symbol ||
+            securityType === undefined ||
+            !isPriceHistorySecurityType(securityType) ||
+            exchange === undefined ||
+            !exchange) {
+            throw new IbkrPriceHistoryContractError(`IBKR returned incomplete contract metadata for conid ${String(conid)}`, "CONTRACT_INVALID");
+        }
+        const contract = { conid, symbol, securityType, exchange };
+        if (symbol !== requestedSymbol ||
+            (expected.securityType !== undefined && expected.securityType !== securityType) ||
+            (expected.exchange !== undefined && expected.exchange !== exchange)) {
+            throw new IbkrPriceHistoryContractError(`IBKR contract ${String(conid)} does not match the requested price-history identity`, "CONTRACT_MISMATCH", [contract]);
+        }
+        return contract;
     }
     /** Discover listed derivative series over an inclusive calendar range. */
     async getDerivativeExpiries(query) {
@@ -3064,8 +3285,8 @@ export class IbkrClient {
         const contracts = [];
         for (let index = 0; index < months.length; index += OPTION_DISCOVERY_MONTH_CONCURRENCY) {
             const batch = months.slice(index, index + OPTION_DISCOVERY_MONTH_CONCURRENCY);
-            const batchContracts = (await Promise.all(batch.map((month) => this.discoverOptions(normalized, month)))).flat();
-            contracts.push(...batchContracts);
+            const batchContracts = await Promise.all(batch.map((month) => this.discoverOptions(normalized, month, right)));
+            contracts.push(...batchContracts.flatMap((result) => result.contracts));
         }
         return [
             ...new Set(contracts
@@ -3074,17 +3295,38 @@ export class IbkrClient {
         ].sort();
     }
     /** Build one exact-expiry chain with canonical OSI symbols and required pricing/greeks. */
-    async getOptionChain(symbol, expiry) {
-        const contracts = (await this.discoverOptions(symbol, monthCode(expiry))).filter((contract) => contract.expiry === expiry);
+    async getOptionChain(symbol, expiry, right) {
+        const month = monthCode(expiry);
+        const normalized = symbol.trim().toUpperCase();
+        const discovery = await this.discoverOptions(normalized, month, right);
+        const contracts = discovery.contracts.filter((contract) => contract.expiry === expiry && (right === undefined || contract.right === right));
         if (!contracts.length) {
             throw new Error(`IBKR returned no option contracts for ${symbol} ${expiry}`);
         }
-        const quoted = await this.fetchOptionQuotes(contracts, { allowIncomplete: true });
+        const quoted = await this.fetchOptionQuotes(contracts, {
+            allowIncomplete: true,
+            telemetry: { symbol: normalized, month, right: right ?? null },
+        });
         if (!quoted.length) {
             throw new Error(`IBKR returned no usable option quotes for ${symbol} ${expiry}`);
         }
         return quoted;
     }
+    /** Return every qualified contract for one exact expiry and side without hiding sparse data. */
+    async getOptionChainSnapshot(symbol, expiry, right) {
+        const month = monthCode(expiry);
+        const normalized = symbol.trim().toUpperCase();
+        const discovery = await this.discoverOptions(normalized, month, right);
+        const contracts = discovery.contracts.filter((contract) => contract.expiry === expiry);
+        if (!contracts.length) {
+            throw new Error(`IBKR returned no ${right} option contracts for ${symbol} ${expiry}`);
+        }
+        return this.fetchOptionChainSnapshot(contracts, discovery.malformedDefinitionCount, {
+            symbol: normalized,
+            month,
+            right,
+        });
+    }
     /** Fetch one exact option quote; null means the contract is not listed. */
     async getOptionQuote(input) {
         const contract = await this.resolveOptionContract(input);
@@ -3137,8 +3379,11 @@ export class IbkrClient {
         return pending;
     }
     /** Resolve one known option directly, without enumerating its month's complete chain. */
-    async loadExactOptionContract(input, month) {
-        const underlying = await this.discoverOptionUnderlying(input.symbol);
+    loadExactOptionContract(input, month) {
+        return this.withSecdefPriming(() => this.loadExactOptionContractPrimed(input, month));
+    }
+    async loadExactOptionContractPrimed(input, month) {
+        const underlying = await this.loadOptionUnderlying(input.symbol);
         const definitions = await this.req({
             path: "iserver/secdef/info",
             params: {
@@ -3220,13 +3465,16 @@ export class IbkrClient {
         }
         return pending;
     }
-    async loadDerivativeContracts(underlying, assetClass, month, requestedExchange, requestedRight, requestedStrike) {
+    loadDerivativeContracts(underlying, assetClass, month, requestedExchange, requestedRight, requestedStrike) {
+        return this.withSecdefPriming(() => this.loadDerivativeContractsPrimed(underlying, assetClass, month, requestedExchange, requestedRight, requestedStrike));
+    }
+    async loadDerivativeContractsPrimed(underlying, assetClass, month, requestedExchange, requestedRight, requestedStrike) {
         // IBKR keeps this priming state in the authenticated session. Strikes may be
         // empty when search has not run first, even with otherwise identical params.
-        const search = await this.req({
+        const search = this.parseSecdefSearchResponse(await this.req({
             path: "iserver/secdef/search",
             params: { symbol: underlying, ...(assetClass === "FOP" ? { secType: "FUT" } : {}) },
-        });
+        }));
         const candidates = search.filter((candidate) => candidate.conid !== undefined &&
             candidate.symbol?.trim().toUpperCase() === underlying &&
             candidate.sections?.some((section) => section.secType?.toUpperCase() === assetClass));
@@ -3331,39 +3579,30 @@ export class IbkrClient {
         }
         return result;
     }
-    discoverOptions(symbol, month) {
+    discoverOptions(symbol, month, right) {
         const normalized = symbol.trim().toUpperCase();
-        const key = `${normalized}:${month}`;
+        const key = `${normalized}:${month}:${right ?? "*"}`;
         let pending = this.optionDiscovery.get(key);
-        if (!pending) {
-            pending = this.loadOptionContracts(normalized, month);
-            this.optionDiscovery.set(key, pending);
-        }
-        return pending;
-    }
-    /** Search once per underlying because IBKR uses this call to prime option lookup state. */
-    discoverOptionUnderlying(symbol) {
-        const normalized = symbol.trim().toUpperCase();
-        let pending = this.optionUnderlyingDiscovery.get(normalized);
-        if (!pending) {
-            pending = this.loadOptionUnderlying(normalized).catch((error) => {
-                this.optionUnderlyingDiscovery.delete(normalized);
-                throw error;
-            });
-            this.optionUnderlyingDiscovery.set(normalized, pending);
+        if (!pending && right !== undefined) {
+            const complete = this.optionDiscovery.get(`${normalized}:${month}:*`);
+            if (complete !== undefined) {
+                pending = complete.then((result) => ({
+                    contracts: result.contracts.filter((contract) => contract.right === right),
+                    malformedDefinitionCount: result.malformedDefinitionCount,
+                }));
+            }
         }
+        pending ??= this.loadOptionContracts(normalized, month, right);
+        this.optionDiscovery.set(key, pending);
         return pending;
     }
     async loadOptionUnderlying(symbol) {
         // This search is load-bearing: IBKR silently returns empty definitions unless the current
         // session has first searched the underlying.
-        const search = await this.req({
+        const search = this.parseSecdefSearchResponse(await this.req({
             path: "iserver/secdef/search",
             params: { symbol },
-        });
-        if (!Array.isArray(search)) {
-            throw new Error(`IBKR returned malformed option underlying results for ${symbol}`);
-        }
+        }));
         const candidates = search.flatMap((item) => {
             if (!isUnknownRecord(item))
                 return [];
@@ -3402,94 +3641,211 @@ export class IbkrClient {
             throw new Error(`IBKR lost the selected underlying for ${symbol}`);
         return underlying;
     }
-    async loadOptionContracts(symbol, month) {
-        const underlying = await this.discoverOptionUnderlying(symbol);
-        const strikes = await this.req({
-            path: "iserver/secdef/strikes",
-            params: { conid: String(underlying.conid), sectype: "OPT", month },
+    async loadOptionContracts(symbol, month, right) {
+        const { underlying, requests } = await this.withSecdefPriming(async () => {
+            const searchStarted = this.requestNow();
+            const selectedUnderlying = await this.loadOptionUnderlying(symbol);
+            this.emitOptionDiscoveryTelemetry({
+                phase: "SEARCH",
+                symbol,
+                month,
+                right: right ?? null,
+                durationMs: this.elapsedSince(searchStarted),
+                definitionRequestCount: 0,
+                snapshotBatchCount: 0,
+            });
+            const strikesStarted = this.requestNow();
+            const strikes = await this.req({
+                path: "iserver/secdef/strikes",
+                params: { conid: String(selectedUnderlying.conid), sectype: "OPT", month },
+            });
+            this.emitOptionDiscoveryTelemetry({
+                phase: "STRIKES",
+                symbol,
+                month,
+                right: right ?? null,
+                durationMs: this.elapsedSince(strikesStarted),
+                definitionRequestCount: 0,
+                snapshotBatchCount: 0,
+            });
+            const callStrikes = strikes.call ?? [];
+            const putStrikes = strikes.put ?? [];
+            if (callStrikes.length === 0 && putStrikes.length === 0) {
+                throw new Error(`IBKR returned empty option strikes for ${symbol} ${month} after secdef/search priming`);
+            }
+            const definitionRequests = [
+                ...(right === undefined || right === "C"
+                    ? callStrikes.map((strike) => ({ strike, right: "C" }))
+                    : []),
+                ...(right === undefined || right === "P"
+                    ? putStrikes.map((strike) => ({ strike, right: "P" }))
+                    : []),
+            ];
+            return { underlying: selectedUnderlying, requests: definitionRequests };
         });
-        const requests = [
-            ...(strikes.call ?? []).map((strike) => ({ strike, right: "C" })),
-            ...(strikes.put ?? []).map((strike) => ({ strike, right: "P" })),
-        ];
-        if (!requests.length) {
-            throw new Error(`IBKR returned empty option strikes for ${symbol} ${month} after secdef/search priming`);
-        }
+        const definitionsStarted = this.requestNow();
+        const responses = await Promise.all(requests.map(({ strike, right: requestRight }) => this.req({
+            path: "iserver/secdef/info",
+            params: {
+                conid: String(underlying.conid),
+                sectype: "OPT",
+                month,
+                strike,
+                right: requestRight,
+            },
+        })));
+        this.emitOptionDiscoveryTelemetry({
+            phase: "DEFINITIONS",
+            symbol,
+            month,
+            right: right ?? null,
+            durationMs: this.elapsedSince(definitionsStarted),
+            definitionRequestCount: requests.length,
+            snapshotBatchCount: 0,
+        });
+        if (requests.length === 0)
+            return { contracts: [], malformedDefinitionCount: 0 };
         const contracts = [];
-        for (const batch of chunks(requests, OPTION_SECDEF_INFO_BATCH_SIZE)) {
-            const responses = await Promise.all(batch.map(({ strike, right }) => this.req({
-                path: "iserver/secdef/info",
-                params: {
-                    conid: String(underlying.conid),
-                    sectype: "OPT",
-                    month,
-                    strike,
-                    right,
-                },
-            })));
-            for (const raw of responses.flat()) {
-                const contract = normalizeOptionContract({
-                    conid: raw.conid,
-                    symbol: raw.symbol ?? underlying.symbol,
-                    maturityDate: raw.maturityDate,
-                    right: raw.right,
-                    strike: raw.strike,
-                });
+        let malformedDefinitionCount = 0;
+        for (const response of responses) {
+            if (!Array.isArray(response)) {
+                throw new Error(`IBKR returned malformed option definitions for ${symbol} ${month}`);
+            }
+            for (const raw of response) {
+                if (!isUnknownRecord(raw)) {
+                    malformedDefinitionCount += 1;
+                    continue;
+                }
+                let contract;
+                try {
+                    contract = normalizeOptionContract({
+                        conid: typeof raw["conid"] === "number" ? raw["conid"] : undefined,
+                        symbol: typeof raw["symbol"] === "string" ? raw["symbol"] : underlying.symbol,
+                        maturityDate: typeof raw["maturityDate"] === "string" ? raw["maturityDate"] : undefined,
+                        right: typeof raw["right"] === "string" ? raw["right"] : undefined,
+                        strike: typeof raw["strike"] === "string" || typeof raw["strike"] === "number"
+                            ? raw["strike"]
+                            : undefined,
+                    });
+                }
+                catch {
+                    malformedDefinitionCount += 1;
+                    continue;
+                }
                 if (contract)
                     contracts.push(contract);
+                else
+                    malformedDefinitionCount += 1;
             }
         }
         const unique = [...new Map(contracts.map((contract) => [contract.conid, contract])).values()];
         if (!unique.length) {
-            throw new Error(`IBKR returned no usable option definitions for ${symbol} ${month}`);
+            throw new Error(`IBKR returned no usable option definitions for ${symbol} ${month} (${String(malformedDefinitionCount)} malformed)`);
+        }
+        return { contracts: unique, malformedDefinitionCount };
+    }
+    async fetchOptionChainSnapshot(contracts, malformedDefinitionCount, telemetry) {
+        const fields = [
+            "bid",
+            "ask",
+            "mid",
+            "delta",
+            "volume",
+            "openInterest",
+            "availability",
+            "timestamp",
+        ];
+        const missingFieldCounts = Object.fromEntries(fields.map((field) => [field, 0]));
+        const quotes = await this.fetchNullableOptionQuotes(contracts, telemetry);
+        for (const quote of quotes) {
+            for (const field of fields) {
+                if (quote[field] === null)
+                    missingFieldCounts[field] += 1;
+            }
         }
-        return unique;
+        const diagnostics = {
+            qualifiedCount: contracts.length,
+            returnedCount: quotes.length,
+            malformedDefinitionCount,
+            missingFieldCounts,
+        };
+        return { quotes, diagnostics };
     }
-    async fetchOptionQuotes(contracts, options = {}) {
-        const { allowIncomplete = false } = options;
-        const result = [];
-        const skipped = [];
-        for (const batch of chunks(contracts, OPTION_MARKETDATA_BATCH_SIZE)) {
+    async fetchNullableOptionQuotes(contracts, telemetry) {
+        const quotes = [];
+        const batches = chunks(contracts, OPTION_MARKETDATA_BATCH_SIZE);
+        const snapshotsStarted = this.requestNow();
+        for (const batch of batches) {
             const params = {
                 conids: batch.map((contract) => contract.conid).join(","),
                 fields: OPTION_QUOTE_FIELDS,
             };
             await this.req({ path: "iserver/marketdata/snapshot", params });
             await this.wait(2000);
-            const snapshots = await this.req({
+            const response = await this.req({
                 path: "iserver/marketdata/snapshot",
                 params,
             });
-            const byConid = new Map(snapshots
-                .filter((snapshot) => snapshot.conid !== undefined)
-                .map((snapshot) => [snapshot.conid, snapshot]));
+            if (!Array.isArray(response)) {
+                throw new Error("IBKR returned malformed option market-data snapshots");
+            }
+            const snapshots = response.filter((snapshot) => isUnknownRecord(snapshot) &&
+                typeof snapshot["conid"] === "number" &&
+                Number.isSafeInteger(snapshot["conid"]) &&
+                snapshot["conid"] > 0);
+            const byConid = new Map(snapshots.map((snapshot) => [snapshot.conid, snapshot]));
             for (const contract of batch) {
                 const snapshot = byConid.get(contract.conid);
-                const bid = snapshot ? this.snapshotNumber(snapshot, "84") : undefined;
-                const ask = snapshot ? this.snapshotNumber(snapshot, "86") : undefined;
-                const delta = snapshot ? this.snapshotNumber(snapshot, "7308") : undefined;
-                if (bid === undefined || ask === undefined || delta === undefined) {
-                    if (allowIncomplete) {
-                        skipped.push(contract.symbol);
-                        continue;
-                    }
-                    throw new Error(`IBKR returned incomplete option market data for ${contract.symbol} (bid/ask/delta required)`);
-                }
-                const volume = snapshot ? (this.snapshotVolume(snapshot) ?? null) : null;
-                const openInterest = snapshot ? (this.snapshotNumber(snapshot, "7638") ?? null) : null;
-                result.push({
+                const bid = snapshot ? (this.snapshotNumber(snapshot, "84") ?? null) : null;
+                const ask = snapshot ? (this.snapshotNumber(snapshot, "86") ?? null) : null;
+                const rawAvailability = snapshot?.["6509"];
+                quotes.push({
                     ...contract,
                     bid,
                     ask,
-                    mid: (bid + ask) / 2,
-                    delta,
-                    volume,
-                    openInterest,
-                    availability: normalizeDerivativeDataAvailability(snapshot?.["6509"]),
+                    mid: bid !== null && ask !== null ? (bid + ask) / 2 : null,
+                    delta: snapshot ? (this.snapshotNumber(snapshot, "7308") ?? null) : null,
+                    volume: snapshot ? (this.snapshotVolume(snapshot) ?? null) : null,
+                    openInterest: snapshot ? (this.snapshotNumber(snapshot, "7638") ?? null) : null,
+                    availability: typeof rawAvailability === "string" || typeof rawAvailability === "number"
+                        ? normalizeDerivativeDataAvailability(rawAvailability)
+                        : null,
                     timestamp: snapshot ? this.snapshotTimestamp(snapshot) : null,
                 });
             }
         }
+        if (telemetry !== undefined) {
+            this.emitOptionDiscoveryTelemetry({
+                phase: "SNAPSHOTS",
+                ...telemetry,
+                durationMs: this.elapsedSince(snapshotsStarted),
+                definitionRequestCount: 0,
+                snapshotBatchCount: batches.length,
+            });
+        }
+        return quotes;
+    }
+    async fetchOptionQuotes(contracts, options = {}) {
+        const { allowIncomplete = false, telemetry } = options;
+        const result = [];
+        const skipped = [];
+        for (const quote of await this.fetchNullableOptionQuotes(contracts, telemetry)) {
+            if (quote.bid === null || quote.ask === null || quote.delta === null) {
+                if (allowIncomplete) {
+                    skipped.push(quote.symbol);
+                    continue;
+                }
+                throw new Error(`IBKR returned incomplete option market data for ${quote.symbol} (bid/ask/delta required)`);
+            }
+            result.push({
+                ...quote,
+                bid: quote.bid,
+                ask: quote.ask,
+                mid: (quote.bid + quote.ask) / 2,
+                delta: quote.delta,
+                availability: quote.availability ?? "unavailable",
+            });
+        }
         if (allowIncomplete && skipped.length && skipped.length === contracts.length) {
             const symbol = contracts[0]?.underlying ?? "unknown";
             const expiry = contracts[0]?.expiry ?? "unknown";
@@ -3497,32 +3853,288 @@ export class IbkrClient {
         }
         return result;
     }
-    historyDays(input) {
+    historyInterval(input) {
         if (input.days !== undefined) {
             if (!Number.isFinite(input.days) || input.days <= 0) {
                 throw new Error(`History days must be positive: ${String(input.days)}`);
             }
-            return Math.ceil(input.days);
+            const days = Math.ceil(input.days);
+            const endDay = this.utcDayStart(this.now());
+            return { start: endDay - (days - 1) * DAY_MS, end: endDay + DAY_MS - 1, days };
         }
-        if (input.startDate === undefined || input.endDate === undefined) {
-            throw new Error("Price history requires days or both startDate and endDate");
+        if (!Number.isFinite(input.startDate) || !Number.isFinite(input.endDate)) {
+            throw new Error("Price history boundaries must be finite epoch milliseconds");
         }
-        const duration = input.endDate - input.startDate;
-        if (duration < 0)
+        if (input.endDate < input.startDate) {
             throw new Error("Price history endDate must not precede startDate");
-        return Math.max(1, Math.ceil(duration / 86_400_000) + 1);
+        }
+        const start = this.utcDayStart(input.startDate);
+        const endDay = this.utcDayStart(input.endDate);
+        return { start, end: endDay + DAY_MS - 1, days: (endDay - start) / DAY_MS + 1 };
+    }
+    elapsedSince(startedAt) {
+        return Math.max(0, this.requestNow() - startedAt);
+    }
+    emitOptionDiscoveryTelemetry(event) {
+        try {
+            const result = this.onOptionDiscoveryTelemetry({
+                event: "OPTION_DISCOVERY_PHASE",
+                ...event,
+            });
+            void Promise.resolve(result).catch(() => undefined);
+        }
+        catch {
+            // Telemetry observers cannot change discovery or quote settlement.
+        }
+    }
+    async requestPriceHistory(contract, requestedSymbol, request) {
+        this.onPriceHistoryTelemetry({
+            event: "PRICE_HISTORY_REQUEST",
+            requestedSymbol,
+            resolvedConid: contract.conid,
+            securityType: contract.securityType,
+            exchange: contract.exchange,
+            period: request.period,
+            barSize: "1d",
+        });
+        const history = await this.fetchQuoteHistory(contract.conid, request.period, false, contract.exchange, "1d", request.startTime);
+        if (history === undefined) {
+            throw new Error("IBKR price-history response was unexpectedly unavailable");
+        }
+        return history;
+    }
+    async recoverDailyHistory(contract, symbol, interval, initialCause) {
+        const observed = [];
+        let cause = initialCause;
+        if (interval.days <= 365) {
+            this.onRequestTelemetry({
+                event: "HISTORY_PERIOD_FALLBACK",
+                endpoint: "iserver/marketdata",
+                attempt: 1,
+                delayMs: 0,
+            });
+            let standardBars;
+            try {
+                const history = await this.requestPriceHistory(contract, symbol, {
+                    period: "1y",
+                    startTime: this.historyStartTime(interval.end),
+                });
+                standardBars = this.normalizeHistoryResponse(symbol, history, interval);
+                this.assertHistoryCoverage(symbol, standardBars, interval);
+                return standardBars;
+            }
+            catch (error) {
+                if (standardBars !== undefined)
+                    observed.push(standardBars);
+                if (!this.isChartDataUnavailable(error) &&
+                    !(error instanceof IbkrInsufficientHistoryError)) {
+                    throw error;
+                }
+                cause = error;
+            }
+        }
+        const windows = this.dailyHistoryWindows(symbol, interval, cause);
+        const completed = [];
+        for (const [index, window] of windows.entries()) {
+            this.onRequestTelemetry({
+                event: "HISTORY_WINDOW_FALLBACK",
+                endpoint: "iserver/marketdata",
+                attempt: index + 1,
+                delayMs: 0,
+            });
+            let bars;
+            try {
+                const history = await this.requestPriceHistory(contract, symbol, {
+                    period: `${String(window.days)}d`,
+                    startTime: this.historyStartTime(window.end),
+                });
+                bars = this.normalizeHistoryResponse(symbol, history, window);
+            }
+            catch (error) {
+                if (!this.isChartDataUnavailable(error))
+                    throw error;
+                this.throwInsufficientHistory(symbol, interval, [...observed, ...completed.map(({ bars }) => bars)], error);
+            }
+            try {
+                this.assertHistoryCoverage(symbol, bars, window);
+            }
+            catch (error) {
+                if (!(error instanceof IbkrInsufficientHistoryError))
+                    throw error;
+                this.throwInsufficientHistory(symbol, interval, [...observed, ...completed.map(({ bars: completedBars }) => completedBars), bars], error);
+            }
+            completed.push({ bars, start: window.start, end: window.end });
+        }
+        this.assertHistoryWindowContinuity(symbol, interval, completed);
+        const result = this.mergeHistoryBars(symbol, completed.map(({ bars }) => bars));
+        this.assertHistoryCoverage(symbol, result, interval);
+        return result;
+    }
+    dailyHistoryWindows(symbol, interval, cause) {
+        const maximumPeriodDays = 90;
+        const overlapDays = 7;
+        const windows = [];
+        let end = interval.end;
+        for (;;) {
+            const endDay = this.utcDayStart(end);
+            const start = Math.max(interval.start, endDay - (maximumPeriodDays - 1) * DAY_MS);
+            windows.push({ start, end, days: (endDay - start) / DAY_MS + 1 });
+            if (start === interval.start)
+                return windows;
+            if (windows.length >= 12) {
+                throw new IbkrInsufficientHistoryError(symbol, interval.start, interval.end, null, null, {
+                    cause,
+                });
+            }
+            end = start + overlapDays * DAY_MS - 1;
+        }
+    }
+    normalizeHistoryResponse(symbol, history, interval) {
+        const volumeFactor = history.volumeFactor ?? 1;
+        if (!Number.isFinite(volumeFactor)) {
+            throw new Error(`IBKR returned a non-finite history volume factor for ${symbol}`);
+        }
+        const bars = [];
+        for (const bar of history.data ?? []) {
+            if (!isFiniteHistoryBar(bar)) {
+                throw new Error(`IBKR returned an incomplete or non-finite history bar for ${symbol}`);
+            }
+            const normalized = {
+                datetime: bar.t,
+                open: bar.o,
+                high: bar.h,
+                low: bar.l,
+                close: bar.c,
+                volume: bar.v * volumeFactor,
+            };
+            if (!Number.isFinite(normalized.volume)) {
+                throw new Error(`IBKR returned a non-finite normalized history volume for ${symbol}`);
+            }
+            if (bar.t < interval.start || bar.t > interval.end)
+                continue;
+            bars.push(normalized);
+        }
+        return this.mergeHistoryBars(symbol, [bars]);
+    }
+    mergeHistoryBars(symbol, groups) {
+        const merged = new Map();
+        for (const bar of groups.flat()) {
+            const existing = merged.get(bar.datetime);
+            if (existing !== undefined) {
+                if (existing.open !== bar.open ||
+                    existing.high !== bar.high ||
+                    existing.low !== bar.low ||
+                    existing.close !== bar.close ||
+                    existing.volume !== bar.volume) {
+                    throw new Error(`IBKR returned conflicting history bars for ${symbol} at ${String(bar.datetime)}`);
+                }
+                continue;
+            }
+            merged.set(bar.datetime, bar);
+        }
+        return [...merged.values()].sort((left, right) => left.datetime - right.datetime);
+    }
+    assertHistoryCoverage(symbol, bars, interval) {
+        const availableStart = bars[0]?.datetime ?? null;
+        const availableEnd = bars[bars.length - 1]?.datetime ?? null;
+        const tolerance = Math.min(7 * DAY_MS, interval.end - interval.start);
+        if (availableStart === null ||
+            availableEnd === null ||
+            availableStart > interval.start + tolerance ||
+            availableEnd < interval.end - tolerance) {
+            throw new IbkrInsufficientHistoryError(symbol, interval.start, interval.end, availableStart, availableEnd);
+        }
+    }
+    assertHistoryWindowContinuity(symbol, interval, windows) {
+        const chronological = [...windows].sort((left, right) => left.start - right.start);
+        for (let index = 1; index < chronological.length; index += 1) {
+            const older = chronological[index - 1];
+            const newer = chronological[index];
+            if (older === undefined || newer === undefined)
+                continue;
+            const olderEnd = older.bars[older.bars.length - 1]?.datetime;
+            const newerStart = newer.bars[0]?.datetime;
+            if (olderEnd === undefined || newerStart === undefined || olderEnd < newerStart) {
+                this.throwInsufficientHistory(symbol, interval, chronological.map(({ bars }) => [...bars]), new Error("IBKR returned discontinuous daily history windows"));
+            }
+        }
+    }
+    throwInsufficientHistory(symbol, interval, groups, cause) {
+        const bars = this.mergeHistoryBars(symbol, groups);
+        throw new IbkrInsufficientHistoryError(symbol, interval.start, interval.end, bars[0]?.datetime ?? null, bars[bars.length - 1]?.datetime ?? null, { cause });
+    }
+    utcDayStart(epochMilliseconds) {
+        const date = new Date(epochMilliseconds);
+        return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+    }
+    historyStartTime(epochMilliseconds) {
+        const iso = new Date(epochMilliseconds).toISOString();
+        return `${iso.slice(0, 10).replaceAll("-", "")}-${iso.slice(11, 19)}`;
     }
-    async fetchQuoteHistory(conid, period = "5d", suppressErrors = true) {
+    isChartDataUnavailable(error) {
+        const brokerDetail = error instanceof IbkrBrokerResponseError ? error.detail : undefined;
+        const status = brokerDetail?.statusCode ?? this.httpStatusFromError(error);
+        if (status !== 500)
+            return false;
+        const transportResponse = typeof error === "object" && error !== null
+            ? error.response
+            : undefined;
+        const responseData = typeof transportResponse === "object" && transportResponse !== null
+            ? transportResponse.data
+            : undefined;
+        // Normalized HTTP failures keep the raw payload under `response.body`.
+        const structuredBody = error instanceof IbkrHttpError ? error.response.body : undefined;
+        const body = typeof error === "object" && error !== null ? error.body : undefined;
+        const payload = brokerDetail?.details ?? responseData ?? structuredBody ?? body;
+        const decoded = (() => {
+            if (typeof payload !== "string")
+                return payload;
+            try {
+                return JSON.parse(payload);
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        if (!isUnknownRecord(decoded))
+            return false;
+        let serialized;
         try {
-            return await this.req({
+            serialized = JSON.stringify(decoded);
+        }
+        catch {
+            return false;
+        }
+        if (/auth|entitl|permission|subscription|invalid.{0,20}(?:contract|conid)|ambiguous.{0,20}contract|security definition/i.test(serialized)) {
+            return false;
+        }
+        const diagnosticValues = [decoded["error"], decoded["message"], decoded["text"]].filter((value) => typeof value === "string" && value.trim() !== "");
+        return (diagnosticValues.length > 0 &&
+            diagnosticValues.every((value) => value.trim().toLowerCase() === "chart data unavailable"));
+    }
+    async fetchQuoteHistory(conid, period = "5d", suppressErrors = true, exchange, bar = "1d", startTime) {
+        try {
+            const response = await this.historyRequest({
                 path: "iserver/marketdata/history",
                 params: {
                     conid: String(conid),
+                    ...(exchange === undefined ? {} : { exchange }),
                     period,
-                    bar: "1d",
+                    bar,
                     outsideRth: true,
+                    ...(startTime === undefined ? {} : { startTime }),
                 },
             });
+            if (isUnknownRecord(response) &&
+                response["error"] !== undefined &&
+                response["error"] !== null) {
+                const detail = this.normalizeBrokerError(response["error"], response, "IBKR rejected the market-data history request");
+                throw new IbkrBrokerResponseError(detail.message, detail);
+            }
+            if (!isUnknownRecord(response) || !Array.isArray(response["data"])) {
+                throw new Error("IBKR returned a malformed market-data history response");
+            }
+            return response;
         }
         catch (error) {
             if (!suppressErrors)
@@ -3897,20 +4509,37 @@ export class IbkrClient {
     }
     /** Typed wrapper around the raw client's untyped `request()`. */
     async sendRequest(input) {
-        return (await this.raw.request(input));
+        try {
+            return (await this.raw.request(input));
+        }
+        catch (error) {
+            throw this.normalizeHttpError(error);
+        }
     }
     req(input) {
-        return this.scheduledRequest(input, true);
+        return this.scheduledRequest(input, "SAFE_READ");
+    }
+    historyRequest(input) {
+        return this.scheduledRequest(input, "PRICE_HISTORY");
     }
     singleAttemptRequest(input) {
-        return this.scheduledRequest(input, false);
+        return this.scheduledRequest(input, "SINGLE_ATTEMPT");
     }
-    scheduledRequest(input, retryable) {
+    scheduledRequest(input, retryPolicy) {
         return this.requestScheduler.schedule({
             endpoint: this.requestEndpoint(input.path),
             priority: this.requestPriority(input.path),
-            retryable,
-        }, () => this.sendRequest(input));
+            secdefInfo: input.path === "iserver/secdef/info",
+            retryable: retryPolicy !== "SINGLE_ATTEMPT",
+            retryServerErrors: retryPolicy === "PRICE_HISTORY",
+        }, async () => {
+            try {
+                return await this.sendRequest(input);
+            }
+            catch (error) {
+                throw this.normalizeHttpError(error);
+            }
+        });
     }
     requestPriority(path) {
         if (path === "iserver/accounts" ||
@@ -3946,12 +4575,19 @@ export class IbkrClient {
         if (/temporar(?:ily|y).*(?:block|ban)|(?:ip|access).*(?:temporar(?:ily|y) )?blocked/i.test(this.requestErrorText(error))) {
             return { kind: "TEMPORARILY_BLOCKED" };
         }
-        if (this.httpStatusFromError(error) === 429) {
+        const status = this.httpStatusFromError(error);
+        if (status === 429) {
             const retryAfterMs = this.retryAfterFromError(error);
             return retryAfterMs === undefined
                 ? { kind: "THROTTLED" }
                 : { kind: "THROTTLED", retryAfterMs };
         }
+        if (status !== undefined && status >= 500 && status <= 599) {
+            const retryAfterMs = this.retryAfterFromError(error);
+            return retryAfterMs === undefined
+                ? { kind: "SERVER_ERROR" }
+                : { kind: "SERVER_ERROR", retryAfterMs };
+        }
         return { kind: "OTHER" };
     }
     requestErrorText(error) {
@@ -3978,6 +4614,48 @@ export class IbkrClient {
         })
             .join(" ");
     }
+    normalizeHttpError(error) {
+        if (error instanceof IbkrHttpError)
+            return error;
+        const status = this.httpStatusFromError(error);
+        if (status === undefined)
+            return error;
+        const body = this.httpResponseBody(error);
+        const retryAfter = this.retryAfterHeaderFromError(error) ?? null;
+        const message = body !== ""
+            ? `IBKR HTTP ${String(status)}: ${body}`
+            : error instanceof Error
+                ? error.message.slice(0, 4_096)
+                : `IBKR HTTP ${String(status)}`;
+        return new IbkrHttpError(message, status, { status, body, retryAfter }, { cause: error });
+    }
+    httpResponseBody(error) {
+        if (typeof error !== "object" || error === null)
+            return "";
+        const response = error.response;
+        const responseData = typeof response === "object" && response !== null
+            ? (response.data ??
+                response.body)
+            : undefined;
+        const directBody = error.body;
+        const message = error.message;
+        const rawBody = responseData ?? directBody ?? this.bodyFromRawTransportMessage(message);
+        if (typeof rawBody === "string")
+            return rawBody.slice(0, 4_096);
+        if (rawBody === undefined)
+            return "";
+        try {
+            return JSON.stringify(rawBody).slice(0, 4_096);
+        }
+        catch {
+            return "";
+        }
+    }
+    bodyFromRawTransportMessage(message) {
+        if (typeof message !== "string")
+            return undefined;
+        return /^Response status \d{3}: ([\s\S]*)$/.exec(message)?.[1];
+    }
     httpStatusFromError(error) {
         if (typeof error !== "object" || error === null)
             return undefined;
@@ -3989,18 +4667,24 @@ export class IbkrClient {
         if (directStatusCode !== undefined)
             return directStatusCode;
         if (typeof response === "object" && response !== null) {
-            return this.numberFromUnknown(response.status ??
+            const responseStatus = this.numberFromUnknown(response.status ??
                 response.statusCode);
+            if (responseStatus !== undefined)
+                return responseStatus;
         }
         const message = error.message;
-        if (typeof message === "string") {
-            const match = /\b429\b/.exec(message);
-            if (match)
-                return 429;
-        }
-        return undefined;
+        if (typeof message !== "string")
+            return undefined;
+        const rawStatus = /^Response status (\d{3}):/.exec(message)?.[1];
+        return rawStatus === undefined ? undefined : this.numberFromUnknown(rawStatus);
     }
     retryAfterFromError(error) {
+        if (typeof error !== "object" || error === null)
+            return undefined;
+        const structuredRetryAfter = error instanceof IbkrHttpError ? (error.response.retryAfter ?? undefined) : undefined;
+        return parseRetryAfter(structuredRetryAfter ?? this.retryAfterHeaderFromError(error), this.requestNow());
+    }
+    retryAfterHeaderFromError(error) {
         if (typeof error !== "object" || error === null)
             return undefined;
         const response = error.response;
@@ -4008,9 +4692,8 @@ export class IbkrClient {
             ? response.headers
             : undefined;
         const directHeaders = error.headers;
-        const retryAfterRaw = this.headerValue(responseHeaders, "Retry-After") ??
-            this.headerValue(directHeaders, "Retry-After");
-        return parseRetryAfter(retryAfterRaw);
+        return (this.headerValue(responseHeaders, "Retry-After") ??
+            this.headerValue(directHeaders, "Retry-After"));
     }
     numberFromUnknown(value) {
         if (typeof value === "number")