技能介绍

要解决的问题

Alpaca 的券商 API 有配额，负载高时还会抖。批量回填历史成交、对账 sweeps、多账户并发拉取这类场景，往往几十次调用后就撞上 429。天真的客户端要么盲打指数退避（API 明明已经告诉你何时能重试），要么不做并发控制（一个 worker pool 直接把配额烧光），要么把列表响应当成完整结果（/v1/accounts/activities 和 /v2/stocks/bars 都是靠 token 前进的）。结果是任务跑到一半失败，或者整批任务互相踩踏。

技能如何工作

这里讲的是传输层模式，与语言无关。

1. 每个响应都读限频头。 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（注意是 Unix 秒）。两个用途：主动——Remaining 降到阈值（比如 ≤50）就告警或放慢；被动——收到 429 时按 Reset 等到窗口打开，而不是无脑退避。

2. 按失败类型重试。 429 等到 X-RateLimit-Reset + 约 1s 缓冲；网络错误和 5xx 走指数退避（base * 2^(attempt-1)，base 1s、10 次时尾部是分钟级，适合后台任务，面向用户调用要少几次）；400/403/422 这类不可重试的 4xx 直接抛给上层。可选加 jitter，避免多 worker 同时重试造成惊群。

3. 有界并发。 固定 worker pool（先从 5–8 起），对着限频头调优；同一轮内缓存按实体读取（如账户的 buying power）；协调不了 pool 时，调用间加固定 sleep（如 100ms）当粗粒度下限。

4. 分页循环。 activities 走响应头 X-Next-Page-Token，bars 走 body 里的 next_page_token 再回传为 page_token；后者的 limit 跨所有 symbol 计数、结果按 symbol 再按时间排序，所以单页可能只含前几个 symbol，必须翻到 token 为空。每一页 fetch 都套用第 2 步的重试循环。

5. 超时与批量写入。 每个调用都设 HTTP timeout（15–30s），并使用共享 client／连接池；回写本地库时按 chunk 插入（如每语句 500 行），并保证幂等（upsert）。

适用边界与注意点

限频值按 endpoint 和 plan 而变，market-data 与 broker 不是同一套限额，不要硬编码数字，只对响应头做反应。SSE 流是例外，它本来就该保持长开，这里的 timeout 策略不适用。指数退避的尾部时长对后台 cron 合适，对用户请求偏慢。批处理要打结构化日志并给每条 item 一个 trace/correlation ID，否则部分失败时几乎无法定位。