Limit Genesis API: kuota panggilan, request per detik, kesegaran data, dan error 429
Ringkasan
- Paket Anda menentukan kuota panggilan per 30 hari (dari 500 ribu di Trial sampai 10 juta di Max), limit request per detik (1 sampai 15), dan kesegaran data (60 sampai 5 detik).
- Hanya respons
200yang memakai kuota. Respons304dan error gratis, tetapi tetap mengambil slot di limit request per detik; jika limit terlampaui, server mengembalikan429dan tidak memotong apa pun. - Polling lebih cepat dari
meta.freshness_sectidak membawa data baru: paket Anda mendapat snapshot baru sekali per interval itu, danIf-None-Matchmengubah polling berlebih menjadi respons304gratis.
Limit Genesis API adalah empat batas per key: kuota panggilan untuk periode 30 hari, rate limit dalam request per detik, kesegaran data, dan volume unduhan. Tiga yang pertama ditentukan oleh paket Anda; volume unduhan sama untuk semua: 60 MB data terkompresi per 10 detik. Jika limit apa pun terlampaui, server mengembalikan error 429 dan tidak memotong apa pun.
Limit per paket
| Paket | Panggilan per 30 hari | Request per detik | Kesegaran |
|---|---|---|---|
| Trial, $20/bulan | 500.000 | 1 | 60 dtk |
| Start, $50/bulan | 2.000.000 | 2 | 30 dtk |
| Pro, $100/bulan | 5.000.000 | 5 | 10 dtk |
| Max, $200/bulan | 10.000.000 | 15 | 5 dtk |
Kesegaran data adalah interval saat paket Anda mendapat snapshot baru: setiap 60 detik di Trial, setiap 5 detik di Max. Nilainya ada di respons, pada field meta.freshness_sec. Pembayaran 3 bulan menghemat 10%, 6 bulan menghemat 20%. Perbandingan paket ada di halaman harga Genesis API, dan aturannya ada di bagian Paket & limit pada dokumentasi.
Apa yang memakai kuota
Satu panggilan adalah satu respons 200. Respons 304 (data tidak berubah) serta error 4xx dan 5xx tidak memakai kuota, tetapi dihitung dalam limit request per detik. Request ke /account/usage tidak memakai panggilan.
Kuota berlaku untuk periode 30 hari, bukan bulan kalender. Waktu reset ada di header X-Quota-Reset, field period_resets_at, dan baris "direset …" di profil Anda. Setelah kuota habis, server menjawab 429 rate_limited, dan Retry-After berisi jumlah detik sampai reset, yang bisa berarti beberapa hari.
Header rate limit
Respons dari endpoint data membawa status limit Anda (nilai sebagai ilustrasi):
| Header | Contoh | Yang ditampilkan |
|---|---|---|
X-RateLimit-Limit | 5 | Limit request per detik pada paket Anda |
X-RateLimit-Remaining | 4 | Sisa request di jendela saat ini |
X-RateLimit-Reset | 1785200001 | Waktu Unix saat jendela direset |
X-Quota-Limit | 5000000 | Kuota panggilan untuk periode 30 hari |
X-Quota-Remaining | 4815799 | Sisa panggilan di periode ini |
X-Quota-Reset | 1786492800 | Waktu Unix saat kuota direset |
Retry-After | 1 | Detik yang harus ditunggu sebelum mencoba lagi, pada 429 dan 503 |
Jendela request per detik berdurasi satu detik, jadi pada respons normal X-RateLimit-Reset menunjuk awal detik berikutnya. Sisa kuota pada contoh: 5.000.000 − 184.201 = 4.815.799 panggilan, angka yang sama dengan yang dikembalikan /account/usage.
Endpoint /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": { … }
}
| Field | Tipe | Arti |
|---|---|---|
plan | string | Paket: trial, start, pro atau max |
calls_used | int | Panggilan terpakai di periode saat ini |
calls_limit | int | Kuota panggilan per periode |
rps_limit | int | Limit request per detik |
freshness_sec | int | Keterlambatan data, detik |
period_resets_at | int | Waktu Unix saat kuota direset |
Endpoint ini tersedia di semua paket dan dijelaskan di bagian Penggunaan. Panggil saat bot mulai berjalan, untuk memeriksa paket dan sisa kuota sebelum polling dimulai.
Error 429: rate_limited dan download_limited
| Respons | Kapan muncul | Yang harus dilakukan |
|---|---|---|
429 rate_limited | Request per detik melebihi yang diizinkan paket Anda | Tunggu sesuai Retry-After dan beri jeda antar-request |
429 rate_limited | Kuota periode habis | Tunggu reset atau ganti paket |
429 rate_limited | Unduhan penuh analitik funding lebih cepat dari yang diizinkan | Ambil sebagian dengan coin atau kirim If-None-Match |
429 download_limited | Melebihi 60 MB data terkompresi dalam 10 detik | Tunggu sesuai Retry-After, persempit request dengan filter |
Kode status 429 Too Many Requests didefinisikan di RFC 6585, di mana Retry-After bersifat opsional. Genesis API mengirimkannya pada setiap 429, selalu dalam detik.
Respons di bawah 64 KB tidak dihitung dalam volume unduhan, dan polling semua dataset sesuai kesegaran paket Anda masih jauh di bawah limit. Unduhan penuh analitik funding tanpa coin punya limit sendiri: /funding/analytics/summary dan /funding/analytics/recent sekali per 60 detik, /funding/analytics/daily sekali per 300 detik per key. Request dengan coin dan respons 304 tidak dibatasi; detailnya ada di bagian Analitik funding.
Akses paket dan 403 plan_restricted
| Paket | Yang terbuka |
|---|---|
| Trial | Arbitrase CEX (Spot – Spot, Spot – Futures, Futures – Futures), funding rate dan funding spread, Fair – Last, CEX Pumps – Dumps, open interest, sinyal AI, pencarian koin, /account/usage |
| Start | Semua yang ada di Trial, ditambah saham /arbitrage/stocks, bagian on-chain /onchain/{section}, arbitrase prediksi pada mode exact dan dutch, status platform |
| Pro dan Max | Semua endpoint: DEX – Spot, DEX – Futures, Crosschain, DEX Dumps, order book, analitik funding, analitik pasar prediksi, smart money, transaksi, trader, mode llm dan sport, swap DEX, analitik OnChain dan koin |
Endpoint di luar paket Anda mengembalikan 403, begitu pula request mode=sport ke /predictions/arbitrage di Start:
{
"success": false,
"error": {
"code": "plan_restricted",
"message": "This endpoint is not included in your plan."
}
}
403 tidak memakai kuota. Mencoba ulang tidak ada gunanya: hanya paket yang lebih tinggi yang membuka akses.
Cara menentukan paket sesuai beban Anda
Contoh ilustrasi: sebuah bot melakukan polling tiga endpoint, /arbitrage/spot-spot, /funding/spread dan /market/open-interest, setiap 10 detik sepanjang hari.
- Request per detik: 3 / 10 = 0,3 rata-rata. Jika ketiganya dikirim sekaligus, semuanya jatuh di detik yang sama, dan Trial serta Start mengembalikan
429untuk kelebihannya. - Panggilan per hari: 86.400 / 10 = 8.640 polling, 8.640 × 3 = 25.920 panggilan.
- Panggilan per 30 hari: 25.920 × 30 = 777.600. Itu melebihi kuota Trial sebesar 500.000; di Start angkanya 777.600 / 2.000.000 = 38,88% dari kuota.
- Kesegaran: di Start snapshot diperbarui setiap 30 detik, yaitu 86.400 / 30 = 2.880 kali sehari. Data baru datang dari 2.880 × 3 × 30 = 259.200 panggilan, dan 777.600 − 259.200 = 518.400 sisanya mengembalikan data yang sama.
Bot yang sama dengan polling sesuai kesegaran tiap paket:
| Kesegaran dan polling | Panggilan per 30 hari | Paket | Porsi kuota |
|---|---|---|---|
| Setiap 60 dtk | 129.600 | Trial | 26% |
| Setiap 30 dtk | 259.200 | Start | 13% |
| Setiap 10 dtk | 777.600 | Pro | 16% |
| Setiap 5 dtk | 1.555.200 | Max | 16% |
Polling setiap 10 detik masuk akal mulai dari Pro: 777.600 / 5.000.000 = 15,552% dari kuota, dan limit 5 request per detik cukup untuk mengirim ketiganya sekaligus. Jika bot bisa memakai data berumur 30 detik, Start dengan polling setiap 30 detik memakai 259.200 / 2.000.000 = 12,96% dari kuota.
Polling tanpa panggilan sia-sia: ETag dan Retry-After
Paket Anda mendapat snapshot baru setiap meta.freshness_sec detik, dan polling yang lebih cepat mengembalikan snapshot yang sama dengan meta.updated_at yang sama. Tanpa header If-None-Match, respons seperti itu adalah 200 dan memakai satu panggilan. Dengan header itu, server menjawab 304 tanpa body: kuota tidak tersentuh, tetapi satu slot di limit per detik terpakai.
ETag tidak datang di setiap respons. Dataset penuh mengembalikannya, yaitu request tanpa filter, seperti /funding/spread pada contoh di bawah. Respons yang difilter (coin, min_spread dan lainnya) tidak punya ETag, dan setiap polling memakai satu panggilan: filter menghemat trafik, ETag menghemat kuota. Retry dan kompresi dibahas di cara polling API secara efisien dan di panduan respons dan error.
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]
etag, pause = None, 30
while True:
headers = {"X-API-Key": KEY}
if etag:
headers["If-None-Match"] = etag
r = requests.get(URL, headers=headers, timeout=15)
if r.status_code in (429, 500, 503):
wait = int(r.headers.get("Retry-After", "5"))
if wait > 600: # kuota habis, berhenti di sini
raise SystemExit(f"Kuota habis, reset dalam {wait} dtk")
time.sleep(wait)
continue
r.raise_for_status() # mencoba ulang tidak memperbaiki 401 atau 403
left = r.headers.get("X-Quota-Remaining") # bisa tidak ada
if left is not None and int(left) < 10_000:
print("Kuota hampir habis:", left)
if r.status_code == 200: # pada 304 data tidak berubah
etag = r.headers.get("ETag")
body = r.json()
pause = body["meta"].get("freshness_sec", pause)
print(body["meta"]["count"], "koin dalam respons")
time.sleep(pause)
Mengganti dan memperpanjang paket
- Paket baru berlaku segera setelah pembayaran: limit dan kesegaran baru, kuota mulai dari nol, dan sisa paket sebelumnya hangus. Situs memperingatkan Anda sebelum membayar.
- Memperpanjang paket yang sama menambah hari pada masa aktif dan tidak mereset kuota: periode 30 hari yang berjalan tetap dilanjutkan.
- Key Anda tetap sama saat mengganti atau memperpanjang paket, jadi program Anda tidak perlu diperbarui.
- Diskon periode berlaku pada harga bulanan: Pro untuk 6 bulan adalah $100 × 0,8 × 6 = $480 dari $600, untuk 3 bulan $100 × 0,9 × 3 = $270.
Cara mendapatkan dan menyimpan key dibahas di panduan key Genesis API.
Tanya jawab
Apa yang terjadi jika kuota habis lebih awal?
Server mengembalikan 429 rate_limited dengan Retry-After sampai kuota direset, dan tidak ada yang dipotong. Tunggu periode baru atau bayar paket yang lebih tinggi: berlaku seketika, dengan kuota baru.
Apakah respons 304 dan error dihitung dalam limit?
Tidak dalam kuota: hanya 200 yang memakainya. Tetapi keduanya dihitung dalam limit request per detik: respons 304 dan error mengambil slot di jendela per detik.
Bagaimana cara memeriksa sisa kuota tanpa memakai panggilan?
Baca X-Quota-Remaining di respons data atau panggil /account/usage: request itu tidak memakai panggilan. Baris "Panggilan terpakai" di profil Anda juga menampilkan pemakaian.
Bisakah saya melewati limit dengan beberapa key?
Tidak. Setiap akun mendapat satu key, limit dihitung per key, dan mengganti alamat IP tidak mengubahnya. Membuka beberapa akun untuk menghindari limit melanggar aturan; jika butuh lebih, pindah ke paket yang lebih tinggi.