Genesis API 响应与错误:JSON 格式、ETag 与 304、HTTP 状态码
简而言之
- Genesis API 的成功响应是由
success、data和meta组成的封装;错误响应是success: false加一个带错误码和消息的error对象。 - 在
If-None-Match中带上上一次的 ETag,数据未变化时返回无响应体的304,且 304 不消耗配额。 429和503在Retry-After等待后重试。重试无法解决400、401、403、404或410,需要修改请求、密钥或套餐。
Genesis API 对每个请求都以 JSON 响应,这是一种由键值对象和数组构成的文本数据格式。成功的响应始终使用同一个封装,包含 success、data 和 meta;出错时则返回 HTTP 状态码和 error 对象。状态码会告诉你的程序下一步该做什么:使用数据、等待 Retry-After 秒后重试,或修正请求。
响应封装:success、data 和 meta
文档中 GET /arbitrage/spot-spot 响应的精简版(该端点在所有套餐中可用):
{
"success": true,
"data": [
{
"coin": "FUEL",
"exchange_buy": "ByBit",
"exchange_sell": "Gate",
"spread_pct": 0.11,
…
}
],
"meta": {
"count": 214,
"updated_at": 1783802410,
"freshness_sec": 10,
"plan": "pro"
}
}
| 字段 | 类型 | 内容 |
|---|---|---|
success | boolean | true 表示请求成功,false 表示出错 |
data | 数组或对象 | 端点的数据 |
meta.count | int | data 中的条目数 |
meta.updated_at | int | 数据生成时的 Unix 时间 |
meta.freshness_sec | int | 你的套餐的数据延迟,单位为秒 |
meta.plan | string | 你的套餐,示例中为 pro |
例外是资金费率分析:其 meta 包含 count、updated_at 和 schema_version,没有 freshness_sec 和 plan。封装格式见文档的 响应格式 部分,data 的字段见各端点的页面。
以下三条约定适用于所有端点:
- 空值为
null:例如 DEX – Futures 中的max_position_usd,在交易所不提供持仓上限时为null; - 价差和费率以百分比表示:
"spread_pct": 0.92表示 0.92%,而不是 92%; - 时间戳为 Unix 秒:
1783802410即 2026 年 7 月 11 日 20:40:10 UTC;以字符串形式返回的日期,例如 Cross-chain 中的pool_created_at,在文档中的类型为 string。
data:行数组或对象
data 的形状在各端点的说明中给出。GET /arbitrage/spot-spot 返回数组:每个套利交易对对应一项,相当于网站表格中的一行。GET /account/usage 返回单个对象,内容是你的密钥状态:
curl "https://api.genesisarbitrage.com/v1/account/usage" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"success": true,
"data": {
"plan": "pro",
"calls_used": 184201,
"calls_limit": 5000000,
"rps_limit": 5,
"freshness_sec": 10,
"period_resets_at": 1786492800
},
"meta": { … }
}
/account/usage 在所有套餐中可用,显示你的套餐、配额用量和 freshness_sec:比这更频繁地轮询没有收益。字段说明见 用量,首个请求的完整流程见 快速入门。需要处理多个端点的代码应明确检查数据形状:Python 中用 isinstance(data, list)。
过滤参数:可选,不带参数时返回完整数据集
所有过滤参数都是可选的:不带参数的请求会返回该端点的完整数据集。在 exchange 中用逗号分隔多个交易所,在 coin 中用代币代码指定币种:
curl -G --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-d coin=BTC -d exchange=Binance,OKX -d min_spread=0.5 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
-G 参数会把 -d 参数转换为查询字符串:?coin=BTC&exchange=Binance,OKX&min_spread=0.5。交易所名称请按响应字段中返回的写法填写:ByBit、Gate、MEXC。套利端点的参数见 套利端点指南。
配额按响应计数,而不是按行数:带过滤或不带过滤的请求都算一次调用。过滤会缩小响应体,从而减少流量和下载限额的占用。所有限制见 Genesis API 限制指南。
gzip 压缩
当客户端发送 Accept-Encoding: gzip 请求头时,Genesis API 会以 gzip 压缩方式发送完整数据集和较大的响应(RFC 9110,第 12.5.3 节)。较小的响应可能不压缩。
Python 的 requests 会自动发送该请求头并解压响应。curl 在没有 --compressed 参数时不会请求压缩;加上该参数后,它会请求并自动解压。
下载限额按压缩后的数据计算:每个密钥每 10 秒最多 60 MB,小于 64 KB 的响应不计入。超出限额会返回 429 download_limited。
ETag 与 304:跳过未变化的数据
ETag 是一个响应头,包含数据的版本标签。客户端在 If-None-Match 请求头中把该标签发回。数据未变化时,服务器返回无响应体的 304 Not Modified;数据已变化时,返回正常的 200,带新数据和新的 ETag。
# 完整数据集,不带过滤:只打印响应头
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
# 带上第一次响应中的 ETag 重复请求(示例值)
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
-H 'If-None-Match: W/"5d1f0c9a"'
ETag 随不带过滤的请求的响应返回,并随每个新的数据快照而变化。带过滤的请求的响应是为该请求单独生成的,不带 ETag;此时由过滤本身节省流量。ETag 对变化缓慢的数据最有用:资金费率分析 汇总的 ETag 大约每 15 分钟变化一次,304 响应不计入它的完整下载限额。
304 响应不消耗配额,但会计入每秒请求数限制。请原样发回标签:根据 RFC 9110,标签是带引号的字符串,W/ 前缀表示弱标签。
错误码与处理方式
出错时,Genesis API 会返回对应的 HTTP 状态码,以及带 success: false 的响应体:
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Requests per second limit exceeded."
}
}
error.code 是机器可读的错误码,你的程序可以据此分支处理。error.message 是给人看的说明:400 时给出原因,410 时给出替代地址。
| HTTP | error.code | 含义 | 处理方式 |
|---|---|---|---|
400 | bad_request | 请求参数无效,例如 /orderbooks/exec 上的 volume=700 | 按 message 修正参数:同样的请求还会失败 |
401 | invalid_key | 密钥缺失、无效或已吊销,或 API 订阅已过期 | 检查 X-API-Key 请求头和个人资料中的订阅状态 |
403 | plan_restricted | 你的套餐不包含该端点 | 升级到包含它的 套餐,或放弃该请求 |
404 | not_found | 找不到端点或资源:数据集、板块、币种、订单簿 | 对照文档检查路径和参数 |
410 | gone | 该端点已下线 | 改用 message 中给出的地址 |
429 | rate_limited | 超出每秒请求数限制,或周期配额已用完 | 等待 Retry-After 秒并放慢速度;配额用完则等待重置或升级套餐 |
429 | download_limited | 下载量超限:每个密钥每 10 秒 60 MB 压缩数据 | 等待 Retry-After,通过过滤、coin 和 If-None-Match 减少流量 |
500 | internal_error | 内部错误 | 稍后重试;若持续出现,请携带 X-Request-Id 联系支持 |
503 | snapshot_not_ready | 数据正在重建,或其数据源正在重启 | Retry-After 秒后重试 |
Retry-After 响应头随 429 和 503 返回,内容是需要等待的秒数:通常是几秒,但周期配额用完时,它是距离配额重置的时间,可能长达数天。4xx 和 5xx 错误不消耗配额,但会计入每秒请求数限制,因此过早重试多半会得到同样的错误。术语表:HTTP 429 和 rate limit。
X-Request-Id:发给支持团队的信息
每个 Genesis API 响应,无论成功与否,都带有包含请求标识符的 X-Request-Id 响应头。如果错误反复出现,或数据看起来不对,请发给支持团队:
X-Request-Id的值;- 请求时间(UTC);
- 端点及其参数,例如
GET /arbitrage/spot-spot?coin=BTC; - HTTP 状态码和
error.code。
不要发送你的密钥。如果密钥出现在聊天记录、日志或他人可见的代码中,请在个人资料中重新生成:旧密钥会立即失效。
响应处理顺序
检查状态码
200:读取data和meta,如果返回了 ETag 就保存下来。304:使用上一次响应中的数据。处理临时错误
等待时间较短的
429和503:等待Retry-After秒后重试,连续最多三次。500:稍后重试。请求类错误直接停止
400、401、403、404、410,以及等待时间长达数小时或数天的429:修正参数、密钥或套餐,或等待配额重置。检查数据时效
把
meta.updated_at与当前时间比较:基于旧快照操作的机器人看到的价差可能早已消失。安排下一次请求
至少间隔
meta.freshness_sec秒,不带过滤的请求使用If-None-Match。
Python 中的 get_json 函数
该函数把上述规则整合在一起:为每个地址保存最近的 ETag,304 时返回上一次的数据;遇到 429 和 503 时等待 Retry-After 并最多重试三次,但不会等待超过一分钟的停顿。其他错误会抛出异常,包含状态码、消息和 X-Request-Id。密钥取自环境变量 GENESIS_API_KEY。
import os
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {} # (path, params) -> (ETag, data)
class GenesisError(Exception):
def __init__(self, status, text):
super().__init__(f"{status} {text}")
self.status = status
def get_json(path, params=None):
key = (path, tuple(sorted((params or {}).items())))
for attempt in range(4): # 一次请求加最多 3 次重试
hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
r = session.get(BASE + path, params=params,
headers=hdr, timeout=15)
if r.status_code == 304:
return cache[key][1] # 数据未变化
wait = float(r.headers.get("Retry-After", 1))
if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
time.sleep(wait) # 不等待数小时或数天
continue
try:
body = r.json()
except ValueError:
raise GenesisError(r.status_code, "不是 JSON") from None
if r.status_code != 200 or not body.get("success"):
err = body.get("error") or {}
raise GenesisError(r.status_code, (
f"{err.get('code')}: {err.get('message')}; "
f"X-Request-Id {r.headers.get('X-Request-Id')}"))
if "ETag" in r.headers: # 仅限不带过滤的响应
cache[key] = (r.headers["ETag"], body["data"])
return body["data"]
timeout=15 参数必不可少:没有超时的话,requests 会一直等待响应。
按套餐的间隔轮询:完整数据集带 ETag,行在代码中过滤。4xx 错误会终止程序;服务器故障则等待下一个周期。
pause = get_json("/account/usage")["freshness_sec"]
while True:
try:
rows = get_json("/arbitrage/spot-spot") # 完整数据集
top = [x for x in rows if x["spread_pct"] >= 1]
print(len(top), "个价差不低于 1% 的交易对")
except GenesisError as e:
if e.status < 500:
raise # 4xx:请求、密钥、套餐或配额
print("服务器错误,下一个周期重试:", e)
time.sleep(pause)
常见问题
304 响应会消耗配额吗?
不会。只有 200 响应消耗配额。304 响应以及 4xx 和 5xx 错误是免费的,但会计入每秒请求数限制。
收到 410 后该怎么办?
该端点已下线,替代地址在 error.message 中。例如,GET /arbitrage/predictions 已于 2026 年 11 月 15 日下线,其 message 指向 /predictions/arbitrage。请更新代码中的路径。
没有报错,为什么 data 是空的?
过滤条件剔除了所有行:例如 min_spread 高于当前所有价差。这样的响应中 meta.count 等于 0,请放宽过滤条件。
为什么响应中没有 ETag?
ETag 随不带过滤的请求的响应返回。带有 coin、exchange、min_spread 或其他过滤参数的请求,其响应是为该请求单独生成的,不带标签,因此 If-None-Match 不适用于它。