速率限制

Alpaca 对 Broker API 应用速率限制，以保护平台对每个合作伙伴的稳定性和公平性。本页解释了如何检测你所处的位置、超过限制时会发生什么，以及如何构建能够优雅处理限制的集成。

限制如何应用

Broker API 速率限制在对应方级别应用——也就是说，跨你的整个集成，而不是按最终用户账户。每个合作伙伴都从默认限制开始，并且可以根据已证明的持续使用情况定制限制。由于限制是按合作伙伴设置的并逐案审核，Alpaca 不公布固定的 Broker API 速率限制数字。

速率限制头（在每个响应中返回）

每个 Broker API 响应——不仅仅是 429 响应——都包含头信息，可准确告诉你当前窗口中所处的位置：

最佳实践： 主动监控 X-RateLimit-Remaining，并在它达到零之前放慢速度，而不是等到被限流。

当你超过限制时会发生什么

当你超过限制时，请求会返回 HTTP 429 Too Many Requests。当你收到 429 时，停下来，等待，并使用指数退避重试。 理想情况下，在 X-RateLimit-Reset 指示的时间之前不要重试。

指数退避

与其立即重试被限流的请求（这只会增加负载并产生更多 429），不如等待一小段时间，并在每次后续失败后将其加倍——例如 1 秒，然后 2 秒、4 秒、8 秒——直到达到最大值，直到请求成功。为每次等待添加少量随机性（“抖动”），以便许多客户端不会同步重试。

示例（伪代码）：

delay = 1.0          # seconds
max_delay = 60.0
for attempt in range(max_retries):
    response = send_request()
    if response.status_code != 429:
        break
    sleep(delay + random.uniform(0, 0.5))   # add jitter
    delay = min(delay * 2, max_delay)       # exponential backoff

沙盒与生产限制

沙盒和生产环境不共享相同的速率限制。沙盒是为功能测试而配置的——验证你的集成能正确创建账户、下单、journal 资金并处理响应——其速率限制显著低于生产环境。

因此，在生产环境中轻松工作的请求速率可能会在沙盒中被限流。因此，你在沙盒中观察到的速率限制不是生产环境限制或余量的可靠信号。

沙盒响应包含与生产环境相同的 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头，因此你仍然可以验证客户端是否正确读取它们并正确退避——只是不要将沙盒数字本身视为生产环境的代表。

负载测试

不要使用沙盒进行负载测试。 沙盒用于功能测试，其速率限制远低于生产环境。针对沙盒的负载测试会触及它在生产环境中永远不会触及的限制，因此结果具有误导性，而且此练习主要衡量的是沙盒限流，而不是你的集成。

沙盒也不能忠实替代生产环境的延迟。许多在生产环境中到达真实下游系统的操作（例如订单路由）在沙盒中是模拟的，因此时序和行为会有所不同。

推荐方法： 构建你的集成，使对 Alpaca 的调用可以打桩或模拟，并为负载测试启用该模式。为了保持结果的真实性，让桩根据你从真实生产 API 调用中采样的持续时间来模拟延迟。这样你就可以演练你自己系统的吞吐量、排队和退避逻辑，而不会受沙盒限制的约束。

如果你需要更高的速率限制

提高速率限制将根据已证明的需求进行审核。如果你有真实、持续的提高速率限制需求，请联系 Alpaca 并具体说明驱动因素：你的用例、预期的每分钟峰值请求数以及流量的时间模式。速率限制的存在是为了保持平台对所有人的稳定性，因此提高速率限制是针对真实、有证据的使用情况授予的。