Cara polling API pasar kripto tanpa kena rate limit: ETag, gzip, filter, dan retry setelah 429
Ringkasan
- API biasanya punya tiga limit: request per detik, kuota panggilan per periode, dan volume unduhan. Di Genesis API itu 1 sampai 15 request per detik, 500K sampai 10M panggilan per 30 hari, dan 60 MB data terkompresi per 10 detik per key.
- Tentukan interval polling dari
meta.freshness_sec: polling lebih cepat hanya mengembalikan snapshot yang sama.If-None-Matchmengubah pengulangan menjadi304gratis, gzip dan filter memangkas traffic, dan satu dataset penuh sebagai ganti request per koin menghemat panggilan. - Coba ulang
429dan503setelahRetry-Afterdetik atau, tanpa header itu, dengan exponential backoff plus jitter acak. Token bucket di sisi klien menjaga kecepatan Anda di bawah limit, dan headerX-RateLimit-*sertaX-Quota-*menunjukkan sisa ruang.
Agar polling API tidak kena error 429, atur request Anda berdasarkan tiga limit sekaligus: request per detik, kuota panggilan untuk periode tersebut, dan volume data yang Anda unduh. Lima teknik mencakup semuanya: interval yang tidak lebih pendek dari pembaruan data, conditional request dengan ETag, kompresi gzip, filter sebagai ganti unduhan yang terlalu besar, dan retry setelah jeda yang diminta server. Angka dan kode di bawah ini untuk Genesis API, REST API untuk data pasar kripto, tetapi tekniknya berlaku untuk API HTTP apa pun, termasuk API exchange.
Tiga limit API: request per detik, kuota, dan volume
Rate limit per detik menangkap lonjakan: sekumpulan request yang dikirim sekaligus. Kuota menangkap kecepatan rata-rata Anda sepanjang periode, dan limit volume menangkap unduhan berat meski request-nya sedikit.
| Limit | Yang dihitung | Genesis API | Jika melewati limit |
|---|---|---|---|
| Request per detik | Setiap request, termasuk 304 dan error | 1 di Trial, 2 di Start, 5 di Pro, 15 di Max | 429 rate_limited, Retry-After: 1 |
| Kuota per periode | Hanya respons 200 | 500K, 2M, 5M, 10M panggilan per 30 hari | 429 rate_limited, Retry-After sampai kuota di-reset |
| Volume unduhan | Respons terkompresi 64 KB ke atas | 60 MB per 10 detik per key, di semua paket | 429 download_limited sampai jendela berakhir |
Genesis API tidak pernah menagih request yang melewati limit: 429 tidak memakai kuota dan tidak dikenai biaya. Semua aturan ada di panduan limit Genesis API dan di bagian Paket & limit pada dokumentasi.
API exchange bisa lebih rumit. Binance menghitung bobot request per alamat IP, dan setiap endpoint punya bobot sendiri. Klien yang terus mengirim request setelah 429 terkena pemblokiran IP otomatis dengan status 418, dan yang mengulangi pelanggaran diblokir lebih lama (dokumentasi Binance).
Interval polling: berapa panggilan yang terpakai dalam 30 hari
Polling lebih cepat daripada pembaruan data hanya menghasilkan pengulangan. Inti Genesis Arbitrage memperbarui data setiap detik, sedangkan output API untuk paket Anda diperbarui sekali tiap meta.freshness_sec detik: 60 di Trial, 30 di Start, 10 di Pro, dan 5 di Max. Itulah kesegaran data paket Anda dan batas bawah interval polling Anda. Genesis API tidak punya WebSocket atau webhook, jadi data diambil lewat polling REST.
Contoh ilustrasi: bot di paket Start — $50 per bulan, 2M panggilan, 2 request per detik, kesegaran 30 detik — melakukan polling empat endpoint: /arbitrage/spot-spot, /arbitrage/spot-futures, /funding/spread, dan /market/open-interest.
| Interval | Panggilan per 30 hari | Porsi kuota Start | Pengulangan satu snapshot |
|---|---|---|---|
| 60 dtk | 172.800 | 8,64% | tidak ada |
| 30 dtk | 345.600 | 17,28% | tidak ada |
| 10 dtk | 1.036.800 | 51,84% | 2 dari 3 |
| 5 dtk | 2.073.600 | 103,68% | 5 dari 6 |
Polling tiap 5 detik menghabiskan kuota pada hari ke-29: 4 × 86.400 / 5 = 69.120 panggilan per hari, dan 2.000.000 / 69.120 ≈ 28,9 hari. Lima dari setiap enam respons mengulang satu snapshot dengan meta.updated_at yang sama, dan tanpa If-None-Match masing-masing memakan satu panggilan.
Pada satu polling tiap 30 detik, kecepatan rata-ratanya 4 / 30 ≈ 0,13 request per detik. Tetapi empat request yang dikirim sekaligus jatuh di detik yang sama, dan dua di antaranya kena 429. Jika Anda butuh data yang lebih segar dari 30 detik, jawabannya adalah paket dengan freshness_sec lebih rendah: Pro memperbarui snapshot tiap 10 detik, Max tiap 5 detik.
Conditional request: ETag, If-None-Match, dan 304
ETag adalah tag versi pada respons. Klien menyimpannya dan mengirimkannya kembali di header If-None-Match pada request berikutnya ke URL yang sama; jika versi tidak berubah, server membalas 304 Not Modified. Menurut RFC 9110, 304 berakhir setelah header dan tidak membawa body, jadi Anda memakai salinan data Anda sendiri.
Di Genesis API, 304 tidak memakai kuota tetapi tetap mengambil satu slot dalam limit request per detik. Hanya dataset penuh tanpa filter yang mendapat tag. Respons untuk request dengan coin, exchange, min_spread atau filter lain, juga /orderbooks/book dan /orderbooks/coin/{coin}, dibuat per request dan datang tanpa ETag.
ETag menghemat kuota jika data berubah lebih jarang daripada frekuensi Anda meminta. Tag pada spread berubah di setiap snapshot, jadi jika Anda polling sekali per freshness_sec, hampir setiap respons adalah 200.
Contoh ilustrasi di Pro: jumlah harian dari analitik funding, /funding/analytics/daily, dibuat ulang tiap jam; setelah riwayat setahun terkumpul, bagian penuhnya sekitar 12 MB gzip, dan tanpa coin ia disajikan paling banyak sekali per 300 detik. Polling tiap 300 detik berarti 2.592.000 / 300 = 8.640 request dalam 30 hari. Dengan If-None-Match, bagian itu diunduh 30 × 24 = 720 kali, dan 8.640 − 720 = 7.920 respons lainnya kembali sebagai 304.
Hasilnya: 720 panggilan, bukan 8.640, dan sekitar 8,6 GB traffic, bukan 104 GB. Respons 304 tidak dihitung dalam limit unduhan penuh.
Filter dan coin: apa yang menghemat panggilan dan apa yang menghemat traffic
Filter memperkecil respons tetapi tidak jumlah panggilan: kuota menghitung respons, dan request dengan coin=BTC berbiaya sama dengan dataset penuh. Jadi pilihannya bergantung pada mana yang habis lebih dulu, panggilan atau traffic.
Contoh ilustrasi di Start: sebuah bot melacak funding untuk lima koin. Lima request ke /funding/rates dengan coin setiap 30 detik berarti 5 × 86.400 = 432.000 panggilan dalam 30 hari, ditambah lima request per siklus terhadap limit 2 per detik. Satu /funding/rates penuh dengan koin yang dipilih di kode hanya berbiaya 86.400 panggilan, lima kali lebih sedikit, dan mendapat ETag.
| Tugas | Cara meminta | Yang dihemat |
|---|---|---|
| Beberapa koin dari satu dataset | Dataset penuh dengan If-None-Match, filter di kode | Panggilan: satu request, bukan beberapa |
| Satu koin dari bagian yang berat | Parameter coin | Traffic dan limit volume |
| Baris di atas ambang | min_spread, min_volume | Traffic, tetapi setiap polling adalah panggilan |
| Bagian yang lambat secara penuh | Dataset penuh dengan If-None-Match | Panggilan dan traffic |
Bagian terberat milik analitik funding: ringkasan penuh sekitar 600 KB gzip, payout 7 hari sekitar 1 MB, dan jumlah harian hingga 12 MB (Endpoint funding). Potongan satu koin dengan coin dikecualikan dari limit unduhan penuh, yaitu sekali per 60 detik untuk ringkasan dan payout serta sekali per 300 detik untuk jumlah harian.
Kompresi gzip
Kompresi mengurangi jumlah byte di jaringan. Klien memintanya dengan Accept-Encoding: gzip, dan server membalas dengan body terkompresi serta header Content-Encoding: gzip. requests di Python menambahkan gzip ke Accept-Encoding dan mendekompresi respons sendiri; curl melakukan hal yang sama dengan --compressed.
Di Genesis API, kompresi terkait dengan sebuah limit: volume unduhan dihitung dari data terkompresi, 60 MB per 10 detik per key, dan respons di bawah 64 KB tidak dihitung. Dataset penuh dan respons besar datang dalam bentuk gzip saat klien memintanya (Respons dan error Genesis API). Untuk melihat berapa byte body yang sebenarnya melewati jaringan, gunakan variabel size_download milik 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"
Retry setelah 429: Retry-After dan backoff dengan jitter
HTTP 429 Too Many Requests adalah jawaban server untuk klien yang melewati limit. Menurut RFC 6585, respons boleh membawa header Retry-After, dan menurut RFC 9110 nilainya berupa jumlah detik atau tanggal. Genesis API mengirim Retry-After pada setiap 429 dan 503, dalam detik.
Retry tanpa jeda hampir selalu mendapat error yang sama dan mengambil satu slot lagi di jendela per detik. Jika ada Retry-After, tunggu selama yang diminta server. Jika tidak ada, tunggu makin lama secara eksponensial setelah setiap kegagalan: hingga 1, 2, 4, 8 detik.
Jitter, tambahan acak pada jeda, penting saat kliennya banyak: tanpanya, semua yang kena error di detik yang sama akan retry di detik yang sama juga. Fungsi backoff memilih jeda acak antara nol dan langkah saat ini, serta menambahkan sebagian detik ke Retry-After. fetch mencoba ulang 429, 500, dan 503, dan berhenti ketika jedanya lebih dari 10 menit: begitulah tampilan kuota yang habis.
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")
| Respons | Jeda | Retry |
|---|---|---|
429 rate_limited, per detik | Retry-After: 1 plus sebagian detik | Ya |
429 rate_limited, kuota | Sampai kuota di-reset, bisa berhari-hari | Tidak |
429 download_limited | Retry-After, sampai jendela berakhir | Ya, dengan request yang lebih sempit |
503 snapshot_not_ready | Retry-After | Ya |
500, timeout, koneksi terputus | Eksponensial dengan jitter | Ya |
400, 401, 403, 404, 410 | — | Tidak, perbaiki request |
Kuota yang habis dibedakan dari limit per detik lewat Retry-After: satu detik versus berjam-jam atau berhari-hari sampai reset, dengan Monthly call quota exceeded. di body respons. Kode dan body error ada di bagian Error pada dokumentasi.
Rate limiter di sisi klien: token bucket
Retry menangani 429; limiter di sisi klien mencegahnya. Token bucket bekerja begini: token datang dengan kecepatan rate per detik, setiap request mengambil satu, dan bucket kosong membuat Anda menunggu. Kapasitasnya, burst, menentukan berapa request yang bisa keluar berurutan tanpa jeda.
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)
Ambil limit dari kolom rps_limit pada /account/usage (bagian Penggunaan) atau dari header X-RateLimit-Limit. Atur rate sedikit di bawah limit, misalnya 0.9 * rps_limit: latensi jaringan tidak merata, jadi request yang dikirim berjarak setengah detik bisa tiba di server lebih berdekatan.
Pemantauan: header X-RateLimit-* dan X-Quota-*
Respons data membawa status limit Anda: X-RateLimit-Remaining dan X-RateLimit-Reset memberi tahu sisa di jendela per detik dan kapan di-reset, sementara X-Quota-Remaining, X-Quota-Limit, dan X-Quota-Reset memberi sisa kuota, ukurannya, dan waktu unix reset. Lebih berguna daripada satu angka sisa adalah lajunya: berapa porsi kuota yang sudah terpakai pada titik ini dalam periode.
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")
Fungsi ini menunggu jendela di-reset saat limitnya habis, dan memberi peringatan ketika pemakaian kuota mendahului kalender lebih dari 5 poin persentase. Contoh ilustrasi: 70% kuota habis pada hari ke-15, jadi dengan laju yang sama panggilan habis pada hari ke 15 / 0,7 ≈ 21,4 dalam periode. /account/usage memberi angka yang sama tanpa header: calls_used, calls_limit, dan period_resets_at.
Jadwal untuk beberapa endpoint
Dengan beberapa endpoint, masing-masing mendapat intervalnya sendiri, dan request pertama disebar agar tidak keluar sebagai satu gelombang. Pilih interval sesuai tugas, tetapi jangan pernah di bawah freshness_sec: spread membutuhkan laju penuh paket Anda, sedangkan untuk banyak strategi satu menit sudah cukup untuk funding dan open interest.
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))
Di Start itu berarti 86.400 + 43.200 + 43.200 = 172.800 panggilan dalam 30 hari, 8,64% dari kuota: spread tiap 30 detik, funding dan open interest tiap 60 detik. Request pertama keluar berjarak 30 / 3 = 10 detik, lalu setiap endpoint menjaga ritmenya sendiri, dan bucket.take() melindungi dari tabrakan. Bot yang dibangun di atas polling ini, dengan alert Telegram, ada di Bot arbitrase kripto dengan Python.
Apa yang dilakukan saat 503 dan error server
Menurut RFC 9110, 503 Service Unavailable berarti kelebihan beban sementara atau pemeliharaan, dan server boleh menyarankan jeda lewat Retry-After. Di Genesis API ini adalah 503 snapshot_not_ready: data sedang dibangun ulang atau sumbernya sedang restart. Coba ulang setelah Retry-After detik; jedanya biasanya beberapa detik.
Selama belum ada respons segar, bot Anda masih memegang data dari polling terakhir, dan data itu menua. Sebelum mengirim sinyal, bandingkan meta.updated_at dengan waktu sekarang: pasangan dari snapshot berumur semenit mungkin sudah hilang di exchange. Risiko lain dibahas di pelajaran Risiko otomatisasi.
Coba ulang 500 internal_error, timeout, dan koneksi terputus dengan exponential backoff. Jika error berlanjut, hubungi dukungan dengan nilai X-Request-Id, waktu request dalam UTC, endpoint, dan kode status. Jangan pernah mengirim key Anda.
Tanya jawab
Berapa request per detik yang boleh saya kirim ke Genesis API?
Sebanyak yang diizinkan paket Anda: 1 di Trial, 2 di Start, 5 di Pro, dan 15 di Max. Limit berlaku per key dan mencakup respons 304 serta error. Nilai paket Anda ada di header X-RateLimit-Limit dan di kolom rps_limit pada /account/usage.
Apakah error dan respons 304 mengurangi kuota saya?
Tidak. Hanya respons 200 yang memakai kuota; 304, 429, 503, dan error lain gratis dan tidak dikenai biaya. Namun semuanya mengambil slot dalam limit request per detik, jadi retry tanpa jeda memicu respons 429 baru.
Bagaimana agar tetap di bawah 60 MB per 10 detik?
Aktifkan gzip: limit menghitung data terkompresi. Kirim If-None-Match pada dataset penuh: 304 tidak punya body. Ambil bagian berat seperti analitik funding sebagai potongan coin, dan jangan unduh dataset penuh yang sama lebih sering dari freshness_sec. Respons di bawah 64 KB tidak dihitung, dan menurut dokumentasi, polling setiap dataset pada kesegaran paket Anda muat di bawah limit dengan ruang yang lega.
Apa arti error 429 Too Many Requests?
Server menolak request karena klien melewati limit dalam satu jendela waktu. Respons boleh membawa Retry-After, jumlah detik yang harus ditunggu; tanpanya, gandakan jeda setelah setiap kegagalan. Di Genesis API, 429 datang dengan kode rate_limited atau download_limited.