限流(rate limit)
限流(rate limit)限制客户端在单位时间内可以向 API 发送的请求数。超出限制时,服务器会返回 RFC 6585 中定义的 429 Too Many Requests,并可能附带 Retry-After 请求头,说明需要等待多少秒(见 HTTP 429 错误)。
速率与额度
通常有两种限制:速率(每秒或每分钟的请求数)和额度(每天或每月的调用数)。在 Genesis API 中,两者都取决于套餐:
| 套餐 | 每秒请求数 | 每 30 天调用数 | 满速时额度可用 |
|---|---|---|---|
| Trial | 1 | 500K | 5.8 天 |
| Start | 2 | 2M | 11.6 天 |
| Pro | 5 | 5M | 11.6 天 |
| Max | 15 | 10M | 7.7 天 |
最后一列假设以限速上限不间断请求,且每个响应都是 200。以 Pro 为例:5 × 86,400 = 432,000 次请求/天,5,000,000 / 432,000 ≈ 11.6 天。每秒限制是突发流量的上限,额度则决定平均速度:30 天有 2,592,000 秒,所以 Pro 的可持续平均速度是 5,000,000 / 2,592,000 ≈ 每秒 1.93 次请求。
只有 200 响应会消耗额度;304 响应和错误不会,但仍计入每秒请求数限制。下载量另有限制:每个密钥每 10 秒 60 MB 压缩数据;超出上限会收到 429 download_limited。
如何不超限
Genesis API 的每个响应都在请求头中报告限流状态:
| 请求头 | 含义 |
|---|---|
X-RateLimit-Limit | 你的套餐每秒请求数上限 |
X-RateLimit-Remaining | 当前窗口内剩余的请求数 |
X-RateLimit-Reset | 窗口重置的 Unix 时间 |
Retry-After | 重试前需等待的秒数(用于 429 和 503) |
额度显示在 X-Quota-Limit、X-Quota-Remaining、X-Quota-Reset 以及用量接口 /account/usage 中。下面的代码依次轮询三个接口:窗口内没有剩余请求时,它会自己等到 X-RateLimit-Reset,遇到 429 和 503 则按 Retry-After 暂停。
import os
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
PATHS = ("/arbitrage/spot-spot", "/funding/spread",
"/market/open-interest")
def poll_once():
for path in PATHS:
r = requests.get(BASE + path, headers=HEADERS, timeout=10)
if r.status_code in (429, 503):
# 服务器要求暂停;下一轮再重试
time.sleep(int(r.headers.get("Retry-After", "1")))
continue
r.raise_for_status()
print(path, "rows:", r.json()["meta"]["count"])
if r.headers.get("X-RateLimit-Remaining") == "0":
# 窗口用尽:等它重置,而不是吃 429
reset = int(r.headers.get("X-RateLimit-Reset", "0"))
time.sleep(max(0.0, reset - time.time()))
while True:
poll_once()
time.sleep(10) # Pro 的数据新鲜度:更频繁的轮询没有收益
另见:API 轮询、数据新鲜度、套餐与限额、Genesis API 限额、如何轮询 API 而不触发限流。
常见问题
月度额度用完后会怎样?
超出额度的请求不会计费。等待重置(时间见 X-Quota-Reset),或升级到更高的套餐:新套餐立即生效,额度从零开始计算,旧套餐剩余的部分作废。
能用第二个密钥绕过限制吗?
不能。一个账户只有一个密钥,使用多个账户或轮换 IP 来绕过限制违反规则。如果调用次数不够,请用筛选条件、coin 参数以及带 If-None-Match 的 ETag 减少不必要的调用,或升级到更高的套餐。