历史数据限制

历史行情不是无限制下载接口。IBKR 会限制请求速度、单次返回数据量、可追溯时间和部分产品的数据类型。写回测、数据同步或批量补数程序时，要先按这些限制设计请求节奏。

官方参考：

先记住三件事

限制	含义	常见后果
不要请求太快	小周期 K 线有明确限频	返回 pacing violation，后续请求可能被拒。
不要一次取太多	`durationStr` 和 `barSizeSetting` 要匹配	请求慢、超时、空结果或被拒绝。
不是所有历史数据都存在	过期衍生品、退市证券、很久以前的小周期数据可能不可用	空结果或错误码。

历史行情开发建议先做单标的、短周期、小窗口测试，再扩大到多标的批量拉取。

常用接口

目标	请求接口	回调
历史 K 线	`reqHistoricalData()`	`historicalData()`、`historicalDataEnd()`、`historicalDataUpdate()`
最早可用时间	`reqHeadTimeStamp()`	`headTimestamp()`
价格直方图	`reqHistogramData()`	`histogramData()`
历史逐笔	`reqHistoricalTicks()`	`historicalTicks()` / `historicalTicksLast()` / `historicalTicksBidAsk()`

reqHistoricalData 参数

app.reqHistoricalData(
    reqId,
    contract,
    endDateTime,
    durationStr,
    barSizeSetting,
    whatToShow,
    useRTH,
    formatDate,
    keepUpToDate,
    chartOptions,
)

参数	类型	中文含义	说明
`reqId`	int	请求编号	自己分配，用来匹配后续回调。
`contract`	`Contract`	合约对象	先确保合约能被 `reqContractDetails()` 识别。
`endDateTime`	str	结束时间	空字符串表示以 TWS 服务器可用时间为结束点；也可传指定时间。
`durationStr`	str	请求跨度	例如 `"1 D"`、`"2 W"`、`"1 M"`。
`barSizeSetting`	str	K 线周期	例如 `"5 mins"`、`"1 hour"`、`"1 day"`。
`whatToShow`	str	数据口径	常见有 `TRADES`、`MIDPOINT`、`BID`、`ASK`、`BID_ASK`。
`useRTH`	int	是否只取常规交易时段	`1` 只取常规交易时段，`0` 包含更多可用时段。
`formatDate`	int	日期格式	`1` 返回可读时间字符串，`2` 返回 Unix 秒级时间戳。
`keepUpToDate`	bool	是否保持更新	`True` 时 `endDateTime` 应为空，可能继续收到 `historicalDataUpdate()`。
`chartOptions`	list	图表选项	Python API 通常传空列表 `[]`。

参考输出

AAPL TRADES 历史 K 线请求：

REQUEST_SENT=reqId=4101;name=aapl_5min_rth;duration=1 D;barSize=5 mins;whatToShow=TRADES;useRTH=1;formatDate=1;keepUpToDate=False
REQUEST_SENT=reqId=4102;name=aapl_1hour_unix;duration=2 D;barSize=1 hour;whatToShow=TRADES;useRTH=1;formatDate=2;keepUpToDate=False
REQUEST_SENT=reqId=4103;name=aapl_keep_up_to_date;duration=1 D;barSize=5 mins;whatToShow=TRADES;useRTH=1;formatDate=1;keepUpToDate=True
CONNECTED=True
CONTRACT=AAPL STK SMART NASDAQ USD
BAR_TOTAL_COUNT=reqId=4101;name=aapl_5min_rth;count=78
BAR=reqId=4101;name=aapl_5min_rth;date=20260612 09:30:00 US/Eastern;open=295.9;high=297.14;low=294.89;close=295.35;volume=1472090;wap=295.893;barCount=10645
BAR_TOTAL_COUNT=reqId=4102;name=aapl_1hour_unix;count=14
BAR=reqId=4102;name=aapl_1hour_unix;date=1781184600;open=293.71;high=293.95;low=290.37;close=291.59;volume=3422903;wap=292.438;barCount=30066
END_COUNT=3
NON_INFO_ERROR_COUNT=0

这说明：

输出	含义
`NON_INFO_ERROR_COUNT=0`	这组历史 K 线请求没有业务错误。
`BAR_TOTAL_COUNT=78`	1 天、5 分钟、常规交易时段返回 78 根 K 线。
`formatDate=1`	`bar.date` 返回可读时间字符串。
`formatDate=2`	`bar.date` 返回 Unix 秒级时间戳。
`keepUpToDate=True`	先返回历史 K 线，交易时段内可能继续进入 `historicalDataUpdate()`。
`END_COUNT=3`	三个请求都收到了 `historicalDataEnd()`。

程序设计建议

确认 Contract
    -> reqHeadTimeStamp() 查询最早可用时间
    -> 按 barSize 选择 duration
    -> 用请求队列控制节奏
    -> 保存 reqId、参数、返回行数、错误码和耗时

每条请求至少记录：

字段	用途
`contract` / `conId`	确认请求的是哪个合约。
`durationStr`	确认单次请求跨度。
`barSizeSetting`	判断是否触发小周期限制。
`whatToShow`	区分成交、买卖价、中间价、收益率等口径。
`useRTH`	区分常规交易时段和全部可用时段。
返回行数	判断是否空结果或被截断。
错误码	区分参数、限频、权限和数据不可用。

不要用反复压测的方式试限频。更稳妥的做法是在程序里主动排队、缓存、记录请求窗口，并把空结果和不可用数据当成可解释状态处理。