技能介绍

要解决什么问题

Alpaca 的 API 有严格限频,高负载下还会偶发抖动。任何调用量稍大的客户端——批量回填、历史数据补齐、对账扫描——都会撞上 429,或被隐藏的配额悄悄拖慢。问题不在单次调用能否成功,而在客户端是否按服务端给出的信号自我调节。这个技能把这类传输层模式整理成跨语言通用的工程实践。

核心能力

1. 每次响应都读限频头

三个标准头:X-RateLimit-Limit(窗口配额)、X-RateLimit-Remaining(剩余量)、X-RateLimit-Reset(窗口重置的 unix 秒)。要点是不只在出错时读:

主动:剩余量降到阈值(如 ≤ 50)时记警告或降速,在触发限流前收手;
被动:遇到 429 时按 Reset 精确等到窗口打开,而不是猜测等待时间。

2. 分层重试策略

429:等待 X-RateLimit-Reset + ~1s 缓冲——服务端已经明确告知何时可重试,盲目指数退避会浪费这个信号;
网络错误与 5xx:指数退避(base * 2^(attempt-1)),可加抖动,避免多个 worker 同步重试形成惊群;
400/403/422 等不可重试的 4xx:直接上抛,重试不会让它们自愈。

3. 有界并发

用固定 worker 池(建议 5–8 个并发)而非无限制扇出,并按限频头调参;批量任务内对重复读取(如账户购买力、转账列表)做运行级缓存,避免同批次重复拉取;无法协调连接池时,调用间加一个小 sleep(如 100ms)作为兜底节流。

4. 完整分页

列表端点不假设一次响应就是全部数据:/v1/accounts/activities 沿响应头 X-Next-Page-Token 翻页;/v2/stocks/bars 沿 body 里的 next_page_token 翻页。特别注意 bars 结果按 symbol 再按时间排序,单页可能只覆盖开头几个 symbol,必须持续翻到 token 为空,且每一页都套用上面的重试循环。

5. 超时与批量写入

每次调用都设 HTTP 超时(15–30s),并复用共享连接池,避免挂起连接拖死整个 worker 池;对账结果写库时按约 500 行分块提交,并用 upsert 保证重复运行幂等。

适用边界

限频数值随端点和套餐而变,行情数据与 broker 配额不同,不要硬编码数字,只响应头部信号;
指数退避在 base 1s、10 次尝试时尾延迟可达分钟级,适合后台任务,但用户面调用应减少尝试次数;
SSE 流是超时规则的例外,它本就应当保持长连接;
使用前建议先读 alpaca-broker-integration;对账幂等见 alpaca-broker-reconciliation-idempotency,行情分页细节见 alpaca-broker-market-data。