چطور API بازار ارز دیجیتال را بدون رسیدن به محدودیت نرخ نظرسنجی کنیم: ETag، gzip، فیلترها و تلاش مجدد پس از 429
به طور خلاصه
- هر API معمولاً سه محدودیت دارد: درخواست در ثانیه، سهمیه فراخوانی در هر دوره و حجم دانلود. در Genesis API اینها 1 تا 15 درخواست در ثانیه، 500K تا 10M فراخوانی در هر 30 روز و 60 مگابایت داده فشرده در هر 10 ثانیه برای هر کلید است.
- فاصله نظرسنجی را از
meta.freshness_secتعیین کنید: نظرسنجی سریعتر همان اسنپشات را برمیگرداند.If-None-Matchتکرار را به یک304رایگان تبدیل میکند، gzip و فیلترها ترافیک را کم میکنند و یک مجموعه داده کامل بهجای یک درخواست برای هر کوین در فراخوانیها صرفهجویی میکند. 429و503را پس ازRetry-Afterثانیه، یا بدون این هدر با عقبنشینی نمایی بههمراه jitter تصادفی دوباره امتحان کنید. 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 | 500K، 2M، 5M، 10M فراخوانی در هر 30 روز | 429 rate_limited، Retry-After تا بازنشانی سهمیه |
| حجم دانلود | پاسخهای فشرده از 64 KB به بالا | 60 MB در هر 10 ثانیه برای هر کلید، در همه پلنها | 429 download_limited تا پایان پنجره |
Genesis API درخواستهای بیش از محدودیت را هرگز محاسبه نمیکند: یک 429 سهمیه مصرف نمیکند و هزینهای ندارد. همه قواعد در راهنمای محدودیتهای Genesis API و در بخش پلنها و محدودیتها مستندات آمده است.
API صرافیها میتواند پیچیدهتر باشد. Binance وزن درخواست را بهازای هر آدرس IP میشمارد و هر endpoint وزن خودش را دارد. کلاینتی که پس از 429 به ارسال ادامه دهد، با وضعیت 418 بهطور خودکار مسدود IP میشود و خاطیان تکراری مدت مسدودی طولانیتری میگیرند (مستندات Binance).
فاصله نظرسنجی: در 30 روز چند فراخوانی مصرف میکنید
نظرسنجی سریعتر از بهروزرسانی داده چیزی جز تکرار نمیآورد. هسته Genesis Arbitrage داده را هر ثانیه بهروز میکند، اما خروجی API برای پلن شما هر meta.freshness_sec ثانیه یک بار تازه میشود: 60 در Trial، 30 در Start، 10 در Pro و 5 در Max. این تازگی داده پلن شماست و کف فاصله نظرسنجی شما. 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% | 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 MB پس از 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 GB ترافیک بهجای 104 GB. پاسخهای 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 KB پس از gzip، پرداختهای 7 روز حدود 1 MB و جمعهای روزانه تا 12 MB (endpointهای فاندینگ). برش یک کوین با coin از محدودیت دانلود کامل معاف است؛ این محدودیت برای خلاصه و پرداختها هر 60 ثانیه یک بار و برای جمعهای روزانه هر 300 ثانیه یک بار است.
فشردهسازی gzip
فشردهسازی تعداد بایتهای روی شبکه را کم میکند. کلاینت با Accept-Encoding: gzip آن را میخواهد و سرور با بدنه فشرده و هدر Content-Encoding: gzip پاسخ میدهد. requests در Python مقدار gzip را به Accept-Encoding اضافه میکند و پاسخ را خودش باز میکند؛ curl هم با --compressed همین کار را میکند.
در Genesis API فشردهسازی به یک محدودیت گره خورده است: حجم دانلود روی داده فشرده شمرده میشود، 60 MB در هر 10 ثانیه برای هر کلید، و پاسخهای زیر 64 KB شمرده نمیشوند. مجموعههای داده کامل و پاسخهای بزرگ، اگر کلاینت بخواهد، با gzip میآیند (پاسخها و خطاهای Genesis API). برای دیدن اینکه واقعاً چند بایت از بدنه از شبکه گذشته، از متغیر size_download در curl استفاده کنید:
# 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 و عقبنشینی با jitter
HTTP 429 Too Many Requests پاسخ سرور به کلاینتی است که از محدودیتی عبور کرده. طبق RFC 6585 پاسخ ممکن است هدر Retry-After داشته باشد و طبق RFC 9110 مقدار آن یا تعداد ثانیه است یا یک تاریخ. Genesis API با هر 429 و 503 هدر Retry-After را به ثانیه میفرستد.
تلاش مجدد بدون مکث تقریباً همیشه همان خطا را میگیرد و یک جایگاه دیگر از پنجره ثانیه را اشغال میکند. اگر 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() # 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، تایماوت، اتصال قطعشده | نمایی با jitter | بله |
400، 401، 403، 404، 410 | — | خیر، درخواست را اصلاح کنید |
سهمیه تمامشده را از محدودیت ثانیه با Retry-After تشخیص میدهید: یک ثانیه در برابر ساعتها یا روزها تا بازنشانی، و Monthly call quota exceeded. در بدنه پاسخ. کدها و بدنه خطاها در بخش خطاها مستندات است.
محدودکننده نرخ سمت کلاینت: token bucket
تلاش مجدد با 429 کنار میآید؛ محدودکننده سمت کلاینت جلوی آن را میگیرد. Token bucket اینطور کار میکند: توکنها با نرخ 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)
محدودیت را از فیلد 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 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 این میشود 86,400 + 43,200 + 43,200 = 172,800 فراخوانی در 30 روز، یعنی 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 چند درخواست در ثانیه میتوانم بفرستم؟
هر تعداد که پلن شما اجازه دهد: 1 در Trial، 2 در Start، 5 در Pro و 15 در Max. محدودیت برای هر کلید است و پاسخهای 304 و خطاها را هم شامل میشود. مقدار پلن شما در هدر X-RateLimit-Limit و در فیلد rps_limit از /account/usage است.
آیا خطاها و پاسخهای 304 از سهمیه من کم میشوند؟
خیر. فقط پاسخ 200 سهمیه مصرف میکند؛ 304، 429، 503 و خطاهای دیگر رایگاناند و هزینهای ندارند. اما جایگاههایی از محدودیت درخواست در ثانیه را میگیرند، پس تلاش مجدد بدون مکث پاسخهای 429 تازه میآورد.
چطور زیر 60 MB در هر 10 ثانیه بمانم؟
gzip را روشن کنید: محدودیت داده فشرده را میشمارد. با مجموعههای داده کامل If-None-Match بفرستید: 304 بدنه ندارد. بخشهای سنگین مانند تحلیل فاندینگ را بهصورت برش coin بگیرید و یک مجموعه داده کامل را بیشتر از هر freshness_sec یک بار دانلود نکنید. پاسخهای زیر 64 KB شمرده نمیشوند و طبق مستندات، نظرسنجی هر مجموعه داده با تازگی پلن شما با حاشیه زیادی زیر محدودیت میماند.
خطای 429 Too Many Requests یعنی چه؟
سرور درخواست را رد کرد چون کلاینت در یک بازه زمانی از محدودیتی عبور کرده است. پاسخ ممکن است Retry-After داشته باشد، یعنی تعداد ثانیههایی که باید صبر کرد؛ بدون آن، مکث را بعد از هر شکست دو برابر کنید. در Genesis API یک 429 با کد rate_limited یا download_limited میآید.