Ответы и ошибки Genesis API: формат JSON, ETag и 304, коды HTTP
Коротко
- Успешный ответ Genesis API — конверт из
success,dataиmeta, ошибка —success: falseи объектerrorс кодом и текстом. - Прошлый ETag в заголовке
If-None-Matchдаёт ответ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: например,max_position_usdв DEX – Фьючерсы равенnull, если биржа размер позиции не отдаёт; - спреды и ставки — в процентах:
"spread_pct": 0.92значит 0,92 %, а не 92 %; - время — unix-секунды:
1783802410— это 11 июля 2026 года, 20:40:10 UTC; даты строкой, как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 — интервал, чаще которого опрашивать данные нет смысла. Поля — в разделе «Использование», первый запрос — в быстром старте. Код, который работает с разными эндпоинтами, проверяет форму явно: isinstance(data, list) в Python.
Фильтры: без них — полный набор
Все параметры фильтров необязательны: запрос без них возвращает полный набор данных эндпоинта. Несколько бирж в 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
Полные наборы и крупные ответы Genesis API отдаёт сжатыми gzip, если клиент передал заголовок Accept-Encoding: gzip (RFC 9110, раздел 12.5.3). Небольшой ответ может прийти без сжатия.
requests в Python сам отправляет этот заголовок и распаковывает ответ. curl без флага --compressed сжатия не запрашивает, с флагом — запрашивает и распаковывает.
Лимит скачивания считает сжатые данные: не больше 60 МБ за 10 секунд на ключ, ответы меньше 64 КБ в него не входят. Сверх лимита приходит 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 помогает на медленных данных: у сводки аналитики фандинга он меняется примерно раз в 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 | Неверные параметры запроса, например volume=700 в /orderbooks/exec | Исправить параметры по 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 | Превышен объём скачивания: 60 МБ сжатых данных за 10 с на ключ | Подождать Retry-After, сократить трафик фильтрами, coin и If-None-Match |
500 | internal_error | Внутренняя ошибка | Повторить позже; если не проходит — написать в поддержку с X-Request-Id |
503 | snapshot_not_ready | Данные пересобираются или источник перезапускается | Повторить через Retry-After секунд |
Заголовок Retry-After приходит с 429 и 503 и содержит число секунд до повтора: обычно единицы секунд, а при исчерпанной квоте периода — время до её сброса, которое может измеряться днями. Ошибки 4xx и 5xx квоту не расходуют, но считаются в лимите запросов в секунду, поэтому повтор раньше срока, скорее всего, вернёт ту же ошибку. Термины — в глоссарии: ошибка 429 и лимит запросов.
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.
Функция get_json на Python
Функция собирает эти правила: хранит 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 = {} # (путь, параметры) -> (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 выведен 15 ноября 2026 года, и его message отсылает к /predictions/arbitrage. Поменяйте путь в коде.
Почему data пустой, хотя ошибки нет?
Фильтры отсекли все строки: например, min_spread выше любого текущего спреда. В таком ответе meta.count равен 0 — ослабьте фильтр.
Почему в ответе нет ETag?
ETag приходит с ответом без фильтров. Ответ на запрос с coin, exchange, min_spread или другим фильтром собирается под запрос и приходит без метки, поэтому If-None-Match к нему не применяется.