Alpaca限频与韧性

要解决的问题

Alpaca 的交易接口是限频的，负载高时也会间歇性抖动。一天里发起几十次以上请求的客户端——批量回填、全量对账、补拉账户流水——很容易撞上 429，然后整批任务卡死或半途失败。更麻烦的是，多数开发者只在报错时才想起限频，于是重试策略要么盲目指数退避，要么干脆不重试，把偶发错误放大成数据不一致。这个技能处理的是传输层问题：怎么写一个能长期跑批、能被反复重跑而不翻车的客户端。

核心能力与关键步骤

1. 每次响应都解析限频头

X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（注意是秒级 unix 时间戳，不是毫秒）。要点是不只在出错时读：

• 主动：Remaining 低于阈值（例如 ≤ 50）时打日志并主动减速；
• 被动：收到 429 时用 Reset 精确睡到窗口打开，而不是拍脑袋退避。

2. 分级重试

• 429 → 睡到 Reset + ~1s 缓冲，这里不要指数退避；
• 网络错误 / 5xx → 指数退避（base * 2^(attempt-1)）加可选 jitter；
• 400/403/422 等不可重试的 4xx → 直接抛出，别重试；
• 后台批任务可以给到约 10 次尝试，用户侧调用要少得多，否则尾延迟失控。

3. 有界并发与批内缓存

用固定 worker 池（从 5–8 起调）替代无上限 fan-out；同一批次里重复的单实体读取（如账户购买力、某账户的转账列表）在本次运行内缓存。无法协调池时，调用间加一个固定小 sleep（如 100ms）做粗粒度下限。

4. 分页必须走循环

/v1/accounts/activities 通过响应头 X-Next-Page-Token 翻页；/v2/stocks/bars 通过 body 里的 next_page_token 回传。后者按 symbol 再按时间排序，一页可能只包含前几个 symbol，所以不能假设一次拿到全部。每页抓取都要套用上面的重试逻辑。

5. 超时、连接池与入库

所有调用都设 HTTP 超时（15–30s 量级），并复用共享客户端/连接池，keep-alive 才有意义；写入自有库时按语句大小分块（例如 500 行一批），配合 upsert 保证可重跑。

适用边界与注意点

• 这些模式是传输层的、语言无关，但不替代业务幂等；重跑安全依赖配套的 idempotency 能力。
• 各端点与套餐的限频额度不同，市场数据与券商是两套计数，不要硬编码具体数字。
• SSE 长连接是例外，它本就该保持打开，不适用上面的超时策略。
• 生产经验：把 worker 池从 10 降到 5，往往能同时缓解券商侧与下游 DB 的压力——调优要看限频头，而不是凭感觉。