如何轮询加密货币行情 API 而不触发限频:ETag、gzip、过滤参数与 429 后重试
简而言之
- API 通常有三类限制:每秒请求数、周期内的调用配额和下载量。Genesis API 的限制是每秒 1 到 15 次请求、每 30 天 500K 到 10M 次调用,以及每个密钥每 10 秒 60 MB 压缩数据。
- 按
meta.freshness_sec设定轮询间隔:轮询得更快,只会拿到同一份快照。If-None-Match把重复请求变成免费的304,gzip 和过滤参数减少流量,一次拉取完整数据集而不是逐币请求则节省调用次数。 - 遇到
429和503,按Retry-After给出的秒数后重试;没有该响应头时,用指数退避加随机抖动。客户端令牌桶让请求速度保持在限额之下,X-RateLimit-*和X-Quota-*响应头显示剩余余量。
要让 API 轮询不出现 429 错误,需要同时围绕三类限制来安排请求:每秒请求数、周期调用配额和下载的数据量。五种做法即可覆盖:间隔不短于数据刷新周期、用 ETag 发条件请求、启用 gzip 压缩、用过滤参数代替过大的下载,以及按服务器要求的停顿时间重试。下文的数字和代码针对 Genesis API,这是一个加密货币行情数据的 REST API,但这些做法适用于任何 HTTP API,包括交易所 API。
API 的三类限制:每秒请求数、配额和下载量
按秒计的限频用来拦截突发流量,也就是一次性发出的一批请求。配额限制整个周期内的平均速度,下载量限制则用来拦截那些请求不多、但数据很重的下载。
| 限制 | 统计对象 | Genesis API | 超限后 |
|---|---|---|---|
| 每秒请求数 | 所有请求,包括 304 和错误 | Trial 为 1,Start 为 2,Pro 为 5,Max 为 15 | 429 rate_limited,Retry-After: 1 |
| 周期配额 | 仅 200 响应 | 每 30 天 500K、2M、5M、10M 次调用 | 429 rate_limited,Retry-After 持续到配额重置 |
| 下载量 | 64 KB 及以上的压缩响应 | 所有套餐均为每个密钥每 10 秒 60 MB | 429 download_limited,直到窗口结束 |
Genesis API 从不对超限请求计费:429 不占用配额,也不产生费用。全部规则见 Genesis API 限额指南和文档中的套餐与限额部分。
交易所 API 可能更复杂。Binance 按 IP 地址统计请求权重,每个 endpoint 都有自己的权重。收到 429 后仍继续发请求的客户端,会被自动封禁 IP,状态码为 418,屡次违规者封禁时间更长(Binance 文档)。
轮询间隔:30 天会用掉多少次调用
轮询得比数据刷新更快,只会得到重复内容。Genesis Arbitrage 核心每秒刷新一次数据,而你的套餐对应的 API 输出每隔 meta.freshness_sec 秒刷新一次:Trial 为 60,Start 为 30,Pro 为 10,Max 为 5。这就是套餐的数据新鲜度,也是轮询间隔的下限。Genesis API 没有 WebSocket 或 webhook,数据通过 REST 轮询获取。
示例(仅作说明):一个使用 Start 套餐的机器人——每月 $50、2M 次调用、每秒 2 次请求、30 秒新鲜度——轮询四个 endpoint:/arbitrage/spot-spot、/arbitrage/spot-futures、/funding/spread 和 /market/open-interest。
| 间隔 | 30 天调用次数 | 占 Start 配额的比例 | 同一快照的重复次数 |
|---|---|---|---|
| 60 秒 | 172,800 | 8.64% | 无 |
| 30 秒 | 345,600 | 17.28% | 无 |
| 10 秒 | 1,036,800 | 51.84% | 3 次中有 2 次 |
| 5 秒 | 2,073,600 | 103.68% | 6 次中有 5 次 |
每 5 秒轮询一次,配额会在第 29 天用完:每天 4 × 86,400 / 5 = 69,120 次调用,2,000,000 / 69,120 ≈ 28.9 天。每六个响应中有五个重复同一份快照,meta.updated_at 相同;没有 If-None-Match 时,每个都要消耗一次调用。
每 30 秒轮询一次时,平均速度为 4 / 30 ≈ 0.13 次请求每秒。但同时发出的四个请求落在同一秒内,其中两个会收到 429。如果需要比 30 秒更新鲜的数据,办法是换用 freshness_sec 更低的套餐:Pro 每 10 秒刷新一次快照,Max 每 5 秒一次。
条件请求:ETag、If-None-Match 与 304
ETag 是响应的版本标签。客户端保存它,并在下次请求同一 URL 时通过 If-None-Match 请求头发回;如果版本没有变化,服务器返回 304 Not Modified。按 RFC 9110,304 在响应头之后即结束,不带响应体,因此你使用自己保存的那份数据。
在 Genesis API 上,304 不占用配额,但仍占用每秒请求数限制中的一个名额。只有不带过滤参数的完整数据集才有标签。带 coin、exchange、min_spread 等过滤参数的请求,以及 /orderbooks/book 和 /orderbooks/coin/{coin},都是按请求实时生成的,不带 ETag。
当数据变化的频率低于你的请求频率时,ETag 才能节省配额。价差数据的标签每个快照都会变化,所以当你每 freshness_sec 轮询一次时,几乎每个响应都是 200。
Pro 套餐示例(仅作说明):资金费率分析的每日汇总 /funding/analytics/daily 每小时重新生成一次;积累满一年历史后,完整部分约为 12 MB gzip,不带 coin 时最多每 300 秒提供一次。每 300 秒轮询一次,30 天共 2,592,000 / 300 = 8,640 次请求。使用 If-None-Match 后,该部分只需下载 30 × 24 = 720 次,其余 8,640 − 720 = 7,920 个响应返回 304。
结果:调用次数从 8,640 降到 720,流量从约 104 GB 降到约 8.6 GB。304 响应不计入完整下载限制。
过滤参数与 coin:哪个省调用,哪个省流量
过滤参数会缩小响应,但不会减少调用次数:配额统计的是响应,带 coin=BTC 的请求与完整数据集花费相同。所以选择取决于哪一项先耗尽,是调用次数还是流量。
Start 套餐示例(仅作说明):一个机器人跟踪五个币种的资金费率。每 30 秒向 /funding/rates 发五次带 coin 的请求,30 天为 5 × 86,400 = 432,000 次调用,而且每个周期的五次请求会冲击每秒 2 次的限制。改为请求一次完整的 /funding/rates,在代码里挑出这些币种,只需 86,400 次调用,少五倍,还能拿到 ETag。
| 任务 | 请求方式 | 节省什么 |
|---|---|---|
| 从同一数据集取多个币种 | 带 If-None-Match 的完整数据集,在代码中过滤 | 调用次数:一次请求代替多次 |
| 从较重的部分取单个币种 | coin 参数 | 流量和下载量限制 |
| 高于阈值的行 | min_spread、min_volume | 流量,但每次轮询都是一次调用 |
| 完整获取更新较慢的部分 | 带 If-None-Match 的完整数据集 | 调用次数和流量 |
最重的部分属于资金费率分析:完整汇总约 600 KB gzip,7 天结算约 1 MB,每日汇总最大 12 MB(资金费率 endpoint)。用 coin 取单币种切片不受完整下载限制约束;该限制对汇总和结算是每 60 秒一次,对每日汇总是每 300 秒一次。
gzip 压缩
压缩可以减少网络上传输的字节数。客户端通过 Accept-Encoding: gzip 请求压缩,服务器返回压缩后的响应体并附带 Content-Encoding: gzip 响应头。Python 的 requests 会在 Accept-Encoding 中加入 gzip 并自动解压响应;curl 则使用 --compressed 实现同样效果。
在 Genesis API 中,压缩与一项限制挂钩:下载量按压缩后的数据统计,每个密钥每 10 秒 60 MB,小于 64 KB 的响应不计入。完整数据集和较大的响应会在客户端请求时以 gzip 返回(Genesis API 响应与错误)。要查看网络上实际传输了多少响应体字节,可以使用 curl 的 size_download 变量:
# body bytes on the wire with and without gzip; each request is a call
URL="https://api.genesisarbitrage.com/v1/funding/rates"
curl -s -o /dev/null --compressed -w "gzip: %{size_download}\n" \
-H "X-API-Key: $GENESIS_API_KEY" "$URL"
curl -s -o /dev/null -w "uncompressed: %{size_download}\n" \
-H "X-API-Key: $GENESIS_API_KEY" "$URL"
429 后重试:Retry-After 与带抖动的退避
HTTP 429 Too Many Requests 是服务器对超限客户端的回应。按 RFC 6585,响应可以带 Retry-After 响应头;按 RFC 9110,它的值是秒数或一个日期。Genesis API 在每个 429 和 503 中都会发送以秒为单位的 Retry-After。
不停顿的重试几乎总会得到同样的错误,还会再占用每秒窗口中的一个名额。如果有 Retry-After,就等待服务器要求的时间。如果没有,则在每次失败后按指数增加等待时间:最长 1、2、4、8 秒。
抖动是在停顿时间上加的随机量,客户端很多时尤其重要:没有它,同一秒内收到错误的所有客户端会在同一秒重试。backoff 函数在零和当前步长之间随机选一个停顿时间,并在 Retry-After 上加上不到一秒的随机量。fetch 会重试 429、500 和 503,当停顿超过 10 分钟时停止:配额耗尽就是这个样子。
import os
import random
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
api = requests.Session() # reuses the TCP connection, gzip is on
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {} # path -> (ETag, data): full datasets only
def backoff(attempt, retry_after=None, cap=60.0):
"""Pause before a retry, in seconds."""
if retry_after and retry_after.isdigit():
return int(retry_after) + random.uniform(0, 1)
return random.uniform(0, min(cap, 2 ** attempt))
def fetch(path, params=None, tries=5):
"""GET from the API: returns (data, response headers)."""
for attempt in range(tries):
tag = None if params else cache.get(path, (None,))[0]
try:
r = api.get(BASE + path, params=params, timeout=15,
headers={"If-None-Match": tag} if tag else {})
except (requests.ConnectionError, requests.Timeout):
time.sleep(backoff(attempt))
continue
if r.status_code == 304: # same snapshot, no quota used
return cache[path][1], r.headers
if r.status_code in (429, 500, 503):
wait = backoff(attempt, r.headers.get("Retry-After"))
if wait > 600: # this is what an exhausted quota looks like
raise RuntimeError(f"quota resets in {wait:.0f} s")
time.sleep(wait)
continue
r.raise_for_status() # 400, 401, 403, 404, 410: do not retry
data = r.json()["data"]
if not params and "ETag" in r.headers:
cache[path] = (r.headers["ETag"], data)
return data, r.headers
raise RuntimeError(f"{path}: no response after {tries} tries")
| 响应 | 停顿 | 是否重试 |
|---|---|---|
429 rate_limited,每秒限制 | Retry-After: 1 再加不到一秒的随机量 | 是 |
429 rate_limited,配额 | 直到配额重置,可能长达数天 | 否 |
429 download_limited | Retry-After,直到窗口结束 | 是,请求要更窄 |
503 snapshot_not_ready | Retry-After | 是 |
500、超时、连接中断 | 带抖动的指数退避 | 是 |
400、401、403、404、410 | — | 否,修正请求 |
配额耗尽与每秒限制可以通过 Retry-After 区分:前者是一秒,后者是距离重置还有数小时或数天,同时响应体中有 Monthly call quota exceeded.。错误码和响应体见文档的错误部分。
客户端限流器:令牌桶
重试处理的是已经出现的 429,客户端限流器则是预防它。令牌桶的工作方式是:令牌以每秒 rate 个的速度生成,每个请求取走一个,桶空了就要等待。容量 burst 决定了能无停顿连续发出多少个请求。
import time
class TokenBucket:
"""At most rate requests per second, up to burst back to back."""
def __init__(self, rate, burst=1):
self.rate, self.burst = rate, burst
self.tokens = float(burst)
self.last = time.monotonic()
def take(self):
while True:
now = time.monotonic()
self.tokens = min(self.burst, self.tokens
+ (now - self.last) * self.rate)
self.last = now
if self.tokens >= 1:
self.tokens -= 1
return
time.sleep((1 - self.tokens) / self.rate)
限额取自 /account/usage 的 rps_limit 字段(见用量部分),或取自 X-RateLimit-Limit 响应头。把速率设得略低于限额,例如 0.9 * rps_limit:网络延迟并不均匀,间隔半秒发出的请求可能更紧挨着到达服务器。
监控:X-RateLimit-* 与 X-Quota-* 响应头
数据响应会带上你的限额状态:X-RateLimit-Remaining 和 X-RateLimit-Reset 给出每秒窗口内的剩余次数及重置时间,X-Quota-Remaining、X-Quota-Limit 和 X-Quota-Reset 则给出剩余配额、配额总量和重置的 unix 时间。比任何单个剩余值更有用的是消耗节奏:在周期中的这一时点,配额已经用掉了多少比例。
PERIOD = 30 * 86400 # Genesis API counts quota per 30 days
def watch(h):
"""Checks limit headroom from the response headers."""
if h.get("X-RateLimit-Remaining") == "0": # window used up
reset = float(h.get("X-RateLimit-Reset", 0))
time.sleep(max(0.0, reset - time.time()))
try:
left = int(h["X-Quota-Remaining"])
limit = int(h["X-Quota-Limit"])
reset = int(h["X-Quota-Reset"])
except (KeyError, ValueError):
return # 429 responses carry no X-Quota-* headers
used = 1 - left / limit
passed = 1 - (reset - time.time()) / PERIOD
if used > passed + 0.05:
print(f"quota is running ahead: {used:.0%} used"
f" with {passed:.0%} of the period gone")
该函数在窗口额度用完时等待其重置,并在配额消耗领先日历进度超过 5 个百分点时发出警告。示例(仅作说明):到第 15 天已用掉 70% 的配额,按同样的速度,调用会在周期的第 15 / 0.7 ≈ 21.4 天耗尽。/account/usage 不需要响应头就能给出同样的数字:calls_used、calls_limit 和 period_resets_at。
多个 endpoint 的调度
有多个 endpoint 时,每个都有自己的间隔,并且把首批请求错开,避免集中发出。按任务选择间隔,但不要低于 freshness_sec:价差数据需要套餐的全速刷新,而对许多策略来说,资金费率和持仓量每分钟一次就够了。
import heapq
usage, _ = fetch("/account/usage") # does not use a call
fresh = usage["freshness_sec"]
bucket = TokenBucket(rate=0.9 * usage["rps_limit"])
JOBS = { # path -> polling interval, s
"/arbitrage/spot-spot": fresh,
"/funding/spread": max(fresh, 60),
"/market/open-interest": max(fresh, 60),
}
t0 = time.monotonic()
queue = [(t0 + i * fresh / len(JOBS), path, every)
for i, (path, every) in enumerate(JOBS.items())]
heapq.heapify(queue)
while True:
due, path, every = heapq.heappop(queue)
time.sleep(max(0.0, due - time.monotonic()))
bucket.take()
data, hdrs = fetch(path)
watch(hdrs)
print(path, len(data))
heapq.heappush(queue, (due + every, path, every))
在 Start 套餐上,30 天为 86,400 + 43,200 + 43,200 = 172,800 次调用,占配额的 8.64%:价差每 30 秒一次,资金费率和持仓量每 60 秒一次。首批请求相隔 30 / 3 = 10 秒发出,之后每个 endpoint 保持自己的节奏,bucket.take() 防止请求撞在一起。基于这种轮询、带 Telegram 提醒的机器人见用 Python 写加密货币套利机器人。
遇到 503 和服务器错误怎么办
按 RFC 9110,503 Service Unavailable 表示临时过载或维护,服务器可以在 Retry-After 中建议停顿时间。在 Genesis API 上,这对应 503 snapshot_not_ready:数据正在重建,或数据源正在重启。按 Retry-After 秒数后重试;停顿通常只有几秒。
在没有新响应期间,机器人手里仍是上一次轮询的数据,而这些数据正在变旧。发出信号之前,把 meta.updated_at 与当前时间比较:一分钟前快照中的交易对,在交易所里可能已经消失。其他风险见自动化风险一课。
对 500 internal_error、超时和连接中断,用指数退避重试。如果错误持续,请联系支持团队,并提供 X-Request-Id 的值、UTC 请求时间、endpoint 和状态码。切勿发送你的密钥。
常见问题
我每秒可以向 Genesis API 发送多少次请求?
以套餐允许的为准:Trial 为 1,Start 为 2,Pro 为 5,Max 为 15。限额按密钥计算,包括 304 响应和错误。你的套餐数值在 X-RateLimit-Limit 响应头和 /account/usage 的 rps_limit 字段中。
错误和 304 响应会消耗我的配额吗?
不会。只有 200 响应会占用配额;304、429、503 和其他错误都是免费的,不产生费用。不过它们会占用每秒请求数限制中的名额,所以不停顿的重试会引发新的 429 响应。
如何保持在每 10 秒 60 MB 以下?
启用 gzip:限制统计的是压缩后的数据。对完整数据集发送 If-None-Match:304 没有响应体。对资金费率分析这类较重的部分,用 coin 切片获取,并且不要比 freshness_sec 更频繁地下载同一个完整数据集。小于 64 KB 的响应不计入,根据文档,按套餐的新鲜度间隔轮询每个数据集,完全在限制之内且有充足余量。
429 Too Many Requests 错误是什么意思?
服务器拒绝了请求,因为客户端在某个时间窗口内超出了限额。响应可以带 Retry-After,即需要等待的秒数;没有的话,每次失败后把停顿时间翻倍。在 Genesis API 中,429 会附带 rate_limited 或 download_limited 代码。