Как опрашивать API крипторынка без превышения лимитов: ETag, gzip, фильтры и повторы после 429
Коротко
- У API обычно три лимита: запросы в секунду, квота вызовов за период и объём скачивания. У Genesis API это от 1 до 15 запросов в секунду, от 500 тыс. до 10 млн вызовов за 30 дней и 60 МБ сжатых данных за 10 секунд на ключ.
- Интервал опроса задаёт
meta.freshness_sec: чаще приходит тот же снимок.If-None-Matchпревращает повтор в бесплатный ответ304, gzip и фильтры сокращают трафик, а один полный набор вместо запросов по каждой монете экономит вызовы. - Ответы
429и503повторяют черезRetry-Afterсекунд, а без этого заголовка — с экспоненциальной паузой и случайной добавкой. Ограничитель token bucket держит темп ниже лимита, а заголовкиX-RateLimit-*иX-Quota-*показывают запас.
Чтобы опрашивать API без ошибки 429, запросы подстраивают сразу под три лимита: число запросов в секунду, квоту вызовов за период и объём скачанных данных. Работают пять приёмов: интервал не чаще обновления данных, условные запросы с ETag, сжатие gzip, фильтры вместо лишних выгрузок и повтор после паузы, которую назвал сервер. Числа и код ниже — для Genesis API, REST API с данными крипторынка, но приёмы подходят к любому HTTP API, включая API бирж.
Три лимита API: запросы в секунду, квота и объём
Лимит запросов в секунду ловит всплески — пачку запросов, отправленных разом. Квота ловит средний темп за весь период, а лимит объёма — тяжёлые выгрузки, даже когда запросов немного.
| Лимит | Что считает | Genesis API | Сверх лимита |
|---|---|---|---|
| Запросы в секунду | Все запросы, включая 304 и ошибки | 1 на Trial, 2 на Start, 5 на Pro, 15 на Max | 429 rate_limited, Retry-After: 1 |
| Квота за период | Только ответы 200 | 500 тыс., 2 млн, 5 млн, 10 млн вызовов за 30 дней | 429 rate_limited, Retry-After до сброса квоты |
| Объём скачивания | Сжатые ответы от 64 КБ | 60 МБ за 10 секунд на ключ, на всех тарифах | 429 download_limited до конца окна |
Запросы сверх лимитов Genesis API не тарифицируются: 429 квоту не тратит и денег не списывает. Все правила — в инструкции «Лимиты Genesis API» и в разделе документации «Тарифы и лимиты».
У API бирж схема бывает сложнее: Binance считает вес запросов по IP-адресу, и у каждого эндпоинта своя цена. Кто продолжает слать запросы после 429, получает автоматическую блокировку IP с кодом 418, а у повторных нарушителей срок растёт (документация Binance).
Интервал опроса: сколько вызовов уйдёт за 30 дней
Опрос чаще, чем обновляются данные, приносит только повторы. Ядро Genesis Arbitrage обновляет данные каждую секунду, а отдача API для тарифа обновляется раз в meta.freshness_sec секунд: 60 на Trial, 30 на Start, 10 на Pro и 5 на Max. Это свежесть данных тарифа и нижняя граница интервала опроса. WebSocket и вебхуков у Genesis API нет, данные забирают опросом по REST.
Условный пример: бот на тарифе Start — $50 в месяц, 2 млн вызовов, 2 запроса в секунду, свежесть 30 с — опрашивает четыре эндпоинта: /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 % | 2 из 3 |
| 5 с | 2 073 600 | 103,68 % | 5 из 6 |
При опросе раз в 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 — метка версии ответа. Клиент сохраняет её и в следующем запросе к тому же адресу отправляет в заголовке 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 МБ gzip, а без coin её отдают не чаще раза в 300 секунд. Опрос раз в 300 секунд — это 2 592 000 / 300 = 8 640 запросов за 30 дней. С If-None-Match секция скачается 30 × 24 = 720 раз, остальные 8 640 − 720 = 7 920 ответов придут как 304.
Итог — 720 вызовов вместо 8 640 и около 8,6 ГБ трафика вместо 104 ГБ. Ответы 304 под ограничение полной выгрузки не попадают.
Фильтры и coin: где экономятся вызовы, а где трафик
Фильтр уменьшает ответ, но не число вызовов: квота считает ответы, и запрос с coin=BTC стоит столько же, сколько полный набор. Поэтому выбор зависит от того, что кончается раньше — вызовы или трафик.
Условный пример на Start: бот следит за фандингом пяти монет. Пять запросов к /funding/rates с coin раз в 30 секунд — 5 × 86 400 = 432 000 вызовов за 30 дней и пять запросов за цикл при лимите 2 в секунду. Один полный /funding/rates с отбором монет в коде — 86 400 вызовов, в пять раз меньше, и к нему подходит ETag.
| Задача | Как запрашивать | Что экономится |
|---|---|---|
| Несколько монет одного набора | Полный набор с If-None-Match, отбор в коде | Вызовы: один запрос вместо нескольких |
| Одна монета тяжёлого раздела | Параметр coin | Трафик и лимит объёма |
| Строки выше порога | min_spread, min_volume | Трафик, но каждый опрос — вызов |
| Медленный раздел целиком | Полный набор с If-None-Match | Вызовы и трафик |
Тяжелее всего аналитика фандинга: полная сводка весит около 600 КБ gzip, выплаты за 7 дней — около 1 МБ, а дневные суммы доходят до 12 МБ («Эндпоинты фандинга»). Срез одной монеты с coin не попадает под лимит полной выгрузки: раз в 60 секунд для сводки и выплат и раз в 300 для дневных сумм.
Сжатие gzip
Сжатие уменьшает число байт, которые идут по сети. Клиент просит его заголовком Accept-Encoding: gzip, сервер отвечает сжатым телом и заголовком Content-Encoding: gzip. Библиотека requests в Python сама добавляет gzip в Accept-Encoding и распаковывает ответ, curl делает то же с флагом --compressed.
В Genesis API сжатие связано с лимитом: объём скачивания считается в сжатых данных, 60 МБ за 10 секунд на ключ, а ответы меньше 64 КБ в него не входят. Полные наборы и крупные ответы приходят в gzip, если клиент его запросил («Ответы и ошибки Genesis API»). Сколько байт тела пришло по сети, показывает переменная size_download в curl:
# байты тела по сети со сжатием и без; каждый запрос — вызов
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 "без сжатия: %{size_download}\n" \
-H "X-API-Key: $GENESIS_API_KEY" "$URL"
Повтор после 429: Retry-After и пауза со случайной добавкой
Ошибка 429 Too Many Requests — ответ сервера на превышение лимита. По RFC 6585 такой ответ может нести заголовок Retry-After, а по RFC 9110 его значение — число секунд или дата. Genesis API присылает Retry-After с каждым 429 и 503, в секундах.
Повтор без паузы почти всегда возвращает ту же ошибку и снова занимает место в секундном окне. Есть Retry-After — ждите столько, сколько просит сервер. Нет — ждите экспоненциально дольше после каждой неудачи: до 1, 2, 4, 8 секунд.
Случайная добавка (jitter) нужна, когда клиентов много: без неё все, кто получил ошибку в одну секунду, повторят запрос тоже в одну секунду. Функция 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() # держит TCP-соединение, gzip включён
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {} # путь -> (ETag, data): только полные наборы
def backoff(attempt, retry_after=None, cap=60.0):
"""Пауза перед повтором, секунды."""
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 к API: возвращает (data, заголовки ответа)."""
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: # снимок прежний, квота цела
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: # так выглядит исчерпанная квота
raise RuntimeError(f"квота: сброс через {wait:.0f} с")
time.sleep(wait)
continue
r.raise_for_status() # 400, 401, 403, 404, 410: не повторять
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}: нет ответа за {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. Коды и тела ошибок — в разделе документации «Ошибки».
Ограничитель запросов на стороне клиента: token bucket
Повтор лечит 429, а ограничитель на стороне клиента его предупреждает. Token bucket («ведро жетонов») устроен так: жетоны прибывают со скоростью rate в секунду, каждый запрос забирает один, а пустое ведро заставляет ждать. Вместимость burst задаёт, сколько запросов уйдёт подряд без паузы.
import time
class TokenBucket:
"""Не больше rate запросов в секунду, подряд до burst."""
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)
Лимит берите из поля rps_limit ответа /account/usage (раздел «Использование») или из заголовка 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 считается за 30 дней
def watch(h):
"""Проверяет запас лимитов по заголовкам ответа."""
if h.get("X-RateLimit-Remaining") == "0": # окно выбрано
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 заголовков X-Quota-* нет
used = 1 - left / limit
passed = 1 - (reset - time.time()) / PERIOD
if used > passed + 0.05:
print(f"квота уходит быстрее срока: {used:.0%} квоты"
f" за {passed:.0%} периода")
Функция ждёт сброса окна, если лимит в нём выбран, и предупреждает, когда расход квоты обгоняет время больше чем на 5 процентных пунктов. Условный пример: к 15-му дню ушло 70 % квоты — при том же темпе вызовы кончатся через 15 / 0,7 ≈ 21,4 дня от начала периода. Те же числа без заголовков даёт /account/usage: calls_used, calls_limit и period_resets_at.
Расписание для нескольких эндпоинтов
Когда эндпоинтов несколько, у каждого свой интервал, а первые запросы разнесены по времени, чтобы не уходить пачкой. Интервал — по задаче, но не меньше freshness_sec: спредам нужна частота тарифа, фандингу и открытому интересу для многих стратегий хватит минуты.
import heapq
usage, _ = fetch("/account/usage") # вызов не списывает
fresh = usage["freshness_sec"]
bucket = TokenBucket(rate=0.9 * usage["rps_limit"])
JOBS = { # путь -> интервал опроса, с
"/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 это 86 400 + 43 200 + 43 200 = 172 800 вызовов за 30 дней, 8,64 % квоты: спреды раз в 30 секунд, фандинг и открытый интерес раз в 60. Первые запросы уходят с шагом 30 / 3 = 10 секунд, дальше каждый эндпоинт держит свой ритм, а 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, эндпоинт и код ответа. Ключ присылать не нужно.
Вопросы и ответы
Сколько запросов в секунду можно отправлять в Genesis API?
Столько, сколько разрешает тариф: 1 на Trial, 2 на Start, 5 на Pro и 15 на Max. Лимит считается на ключ, в него входят ответы 304 и ошибки. Значение тарифа — в заголовке X-RateLimit-Limit и в поле rps_limit ответа /account/usage.
Списываются ли ошибки и ответы 304?
Нет. Квоту тратит только ответ 200, а 304, 429, 503 и другие ошибки бесплатны и денег не списывают. Но они занимают место в лимите запросов в секунду, поэтому повторы без паузы сами вызывают новые 429.
Как не упереться в лимит 60 МБ за 10 секунд?
Включите gzip: лимит считает сжатые данные. Присылайте If-None-Match к полным наборам: 304 приходит без тела. Тяжёлые разделы вроде аналитики фандинга берите срезом с coin, а один полный набор не скачивайте чаще freshness_sec. Ответы меньше 64 КБ в лимит не входят, а опрос всех наборов с частотой тарифа, по документации, укладывается в него с запасом.
Что значит ошибка 429 Too Many Requests?
Сервер отклонил запрос, потому что клиент превысил лимит за отрезок времени. Ответ может нести Retry-After — сколько секунд ждать; без него паузу удваивают после каждой неудачи. В Genesis API 429 приходит с кодом rate_limited или download_limited.