Respons dan error Genesis API: format JSON, ETag dan 304, kode HTTP
Ringkasan
- Respons Genesis API yang berhasil berupa envelope
success,data, danmeta; error berupasuccess: falseplus objekerrorberisi kode dan pesan. - Mengirim ETag sebelumnya di
If-None-Matchmengembalikan304tanpa body jika data tidak berubah, dan 304 tidak memakai kuota. - Coba ulang
429dan503setelah jedaRetry-After. Coba ulang tidak memperbaiki400,401,403,404, atau410— ubah request, key, atau paketnya.
Genesis API menjawab setiap request dalam JSON, format data teks yang terdiri dari objek key–value dan array. Respons yang berhasil selalu datang dalam envelope yang sama berisi success, data, dan meta; error datang dengan kode status HTTP dan objek error. Kode status memberi tahu program Anda langkah berikutnya: memakai datanya, menunggu Retry-After detik lalu mencoba ulang, atau memperbaiki request.
Envelope respons: success, data, dan meta
Respons GET /arbitrage/spot-spot yang dipersingkat dari dokumentasi (endpoint ini tersedia di semua paket):
{
"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"
}
}
| Field | Tipe | Isi |
|---|---|---|
success | boolean | true — request berhasil, false — error |
data | array atau objek | Data endpoint |
meta.count | int | Jumlah item di data |
meta.updated_at | int | Waktu Unix saat data dibuat |
meta.freshness_sec | int | Jeda penyajian untuk paket Anda, dalam detik |
meta.plan | string | Paket Anda, pro pada contoh |
Pengecualiannya adalah analitik funding: meta-nya memuat count, updated_at, dan schema_version, tanpa freshness_sec atau plan. Envelope dijelaskan di bagian Format respons dalam dokumentasi, dan field data ada di halaman setiap endpoint.
Tiga konvensi berlaku untuk semua endpoint:
- nilai kosong adalah
null: misalnyamax_position_usddi DEX – Futures bernilainulljika exchange tidak menyediakan batas posisi; - spread dan rate dalam persen:
"spread_pct": 0.92berarti 0,92%, bukan 92%; - timestamp dalam detik Unix:
1783802410adalah 11 Juli 2026, 20:40:10 UTC; tanggal yang dikirim sebagai string, sepertipool_created_atdi Cross-chain, bertipe string di dokumentasi.
data: array baris atau objek
Bentuk data dijelaskan pada deskripsi setiap endpoint. Untuk GET /arbitrage/spot-spot bentuknya array: satu item per pasangan arbitrase, seperti satu baris tabel di situs. Untuk GET /account/usage bentuknya satu objek berisi status key Anda:
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 tersedia di semua paket dan menampilkan paket, pemakaian kuota, dan freshness_sec Anda: polling lebih sering dari itu tidak ada gunanya. Field dijelaskan di Penggunaan, dan request pertama dibahas langkah demi langkah di panduan cepat. Kode yang bekerja dengan beberapa endpoint sebaiknya memeriksa bentuknya secara eksplisit: isinstance(data, list) di Python.
Filter: opsional, dataset lengkap tanpa filter
Semua parameter filter bersifat opsional: request tanpa filter mengembalikan dataset lengkap endpoint. Tulis beberapa exchange di exchange dengan pemisah koma, dan tentukan coin lewat tickernya di 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"
Flag -G mengubah parameter -d menjadi query string: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Tulis nama exchange seperti yang muncul di field respons: ByBit, Gate, MEXC. Parameter endpoint arbitrase ada di panduan endpoint arbitrase.
Kuota menghitung respons, bukan baris: request dengan atau tanpa filter dihitung satu panggilan. Filter memperkecil body respons, dan bersama itu trafik serta pemakaian batas unduh. Semua batas dibahas di panduan batas Genesis API.
Kompresi gzip
Genesis API mengirim dataset lengkap dan respons besar dalam bentuk gzip jika klien mengirim header Accept-Encoding: gzip (RFC 9110, bagian 12.5.3). Respons kecil bisa datang tanpa kompresi.
requests di Python mengirim header itu sendiri dan mendekompresi respons. curl tidak meminta kompresi tanpa flag --compressed; dengan flag itu, curl meminta dan mendekompresinya.
Batas unduh menghitung data terkompresi: maksimal 60 MB per 10 detik per key, dan respons di bawah 64 KB tidak dihitung. Jika melewati batas, Anda mendapat 429 download_limited.
ETag dan 304: lewati data yang tidak berubah
ETag adalah header respons berisi tag versi data. Klien mengirim tag itu kembali di header If-None-Match. Jika data tidak berubah, server menjawab 304 Not Modified tanpa body; jika berubah, server memberi 200 biasa dengan data baru dan ETag baru.
# Dataset lengkap, tanpa filter: cetak header respons saja
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
# Ulangi dengan ETag dari respons pertama (nilai ilustrasi)
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 datang bersama respons untuk request tanpa filter dan berubah di setiap snapshot data baru. Respons untuk request berfilter dibuat khusus untuk request itu dan datang tanpa ETag; di sana filter itu sendiri yang menghemat trafik. ETag paling berguna pada data yang berubah lambat: ringkasan analitik funding mengganti ETag kira-kira setiap 15 menit, dan balasan 304 tidak dihitung ke batas unduh penuhnya.
Respons 304 tidak memakai kuota tetapi dihitung ke batas request per detik. Kirim tag persis seperti yang diterima: menurut RFC 9110, tag adalah string dalam tanda kutip, dan awalan W/ menandai weak tag.
Kode error dan tindakan yang perlu diambil
Saat terjadi error, Genesis API mengembalikan status HTTP yang sesuai dan body dengan success: false:
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Requests per second limit exceeded."
}
}
error.code adalah kode yang bisa dibaca mesin dan dipakai program Anda untuk bercabang. error.message adalah penjelasan untuk manusia: untuk 400 berisi alasannya, untuk 410 berisi alamat penggantinya.
| HTTP | error.code | Arti | Tindakan |
|---|---|---|---|
400 | bad_request | Parameter request tidak valid, misalnya volume=700 di /orderbooks/exec | Perbaiki parameter sesuai message: request yang sama akan gagal lagi |
401 | invalid_key | Key tidak ada, tidak valid, atau dicabut, atau langganan API berakhir | Periksa header X-API-Key dan status langganan di profil Anda |
403 | plan_restricted | Endpoint tidak ada di paket Anda | Pindah ke paket yang mencakupnya atau hentikan request |
404 | not_found | Endpoint atau resource tidak ditemukan: dataset, bagian, coin, order book | Cocokkan path dan parameter dengan dokumentasi |
410 | gone | Endpoint sudah dihentikan | Pindah ke alamat yang tertera di message |
429 | rate_limited | Batas request per detik terlampaui, atau kuota periode habis | Tunggu Retry-After detik dan perlambat; jika kuota habis, tunggu reset atau tingkatkan paket |
429 | download_limited | Volume unduh terlampaui: 60 MB data terkompresi per 10 detik per key | Tunggu Retry-After, kurangi trafik dengan filter, coin, dan If-None-Match |
500 | internal_error | Error internal | Coba lagi nanti; jika berlanjut, hubungi dukungan dengan X-Request-Id |
503 | snapshot_not_ready | Data sedang dibangun ulang atau sumbernya sedang restart | Coba lagi setelah Retry-After detik |
Header Retry-After datang bersama 429 dan 503 dan berisi jumlah detik yang harus ditunggu: biasanya beberapa detik, tetapi jika kuota periode habis, isinya adalah waktu sampai kuota di-reset, yang bisa berhari-hari. Error 4xx dan 5xx tidak memakai kuota tetapi dihitung ke batas request per detik, sehingga percobaan ulang yang terlalu cepat kemungkinan besar mengembalikan error yang sama. Istilah di glosarium: HTTP 429 dan rate limit.
X-Request-Id: yang perlu dikirim ke dukungan
Setiap respons Genesis API, berhasil atau tidak, membawa header X-Request-Id berisi pengenal request. Jika error terus muncul atau datanya tampak salah, kirim ke dukungan:
- nilai
X-Request-Id; - waktu request dalam UTC;
- endpoint beserta parameternya, misalnya
GET /arbitrage/spot-spot?coin=BTC; - status HTTP dan
error.code.
Jangan kirim key Anda. Jika key sampai masuk ke chat, log, atau kode yang bisa dilihat orang lain, terbitkan ulang di profil Anda: key lama langsung berhenti berfungsi.
Urutan menangani respons
Periksa kode status
200— bacadatadanmeta, dan simpan ETag jika ada.304— pakai data dari respons sebelumnya.Tangani error sementara
429dan503dengan jeda pendek — tungguRetry-Afterdetik lalu coba ulang, paling banyak tiga kali berturut-turut.500— coba lagi nanti.Berhenti pada error request
400,401,403,404,410, dan429dengan jeda berjam-jam atau berhari-hari — perbaiki parameter, key, atau paket, atau tunggu reset kuota.Periksa usia data
Bandingkan
meta.updated_atdengan waktu sekarang: bot yang bertindak berdasarkan snapshot lama melihat spread yang sudah hilang.Jadwalkan request berikutnya
Paling cepat
meta.freshness_secdetik kemudian, denganIf-None-Matchuntuk request tanpa filter.
Fungsi get_json di Python
Fungsi ini menyatukan aturan tersebut: menyimpan ETag terakhir untuk setiap alamat dan mengembalikan data sebelumnya pada 304, menunggu Retry-After pada 429 dan 503 dan mencoba ulang hingga tiga kali, tetapi tidak menunggu jeda lebih dari semenit. Error lain memunculkan exception berisi status, pesan, dan X-Request-Id. Key diambil dari variabel lingkungan 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 = {} # (path, params) -> (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): # satu request plus maksimal 3 percobaan ulang
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] # data tidak berubah
wait = float(r.headers.get("Retry-After", 1))
if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
time.sleep(wait) # jangan menunggu berjam-jam atau berhari-hari
continue
try:
body = r.json()
except ValueError:
raise GenesisError(r.status_code, "bukan 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: # hanya pada respons tanpa filter
cache[key] = (r.headers["ETag"], body["data"])
return body["data"]
Parameter timeout=15 wajib ada: tanpa timeout, requests menunggu respons selamanya.
Polling pada interval paket Anda: dataset lengkap datang dengan ETag, dan baris difilter di kode. Error 4xx menghentikan program; kegagalan server menunggu siklus berikutnya.
pause = get_json("/account/usage")["freshness_sec"]
while True:
try:
rows = get_json("/arbitrage/spot-spot") # dataset lengkap
top = [x for x in rows if x["spread_pct"] >= 1]
print(len(top), "pasangan dengan spread 1% atau lebih")
except GenesisError as e:
if e.status < 500:
raise # 4xx: request, key, paket, atau kuota
print("error server, dicoba lagi di siklus berikutnya:", e)
time.sleep(pause)
Tanya jawab
Apakah respons 304 memakai kuota?
Tidak. Hanya respons 200 yang memakai kuota. Respons 304 serta error 4xx dan 5xx gratis, tetapi dihitung ke batas request per detik.
Apa yang harus dilakukan setelah 410 ?
Endpoint sudah dihentikan, dan alamat penggantinya ada di error.message. Misalnya, GET /arbitrage/predictions dihentikan pada 15 November 2026, dan message-nya menunjuk ke /predictions/arbitrage. Perbarui path di kode Anda.
Mengapa data kosong padahal tidak ada error?
Filter menghapus semua baris: misalnya min_spread di atas semua spread saat ini. Respons seperti itu memiliki meta.count sama dengan 0, jadi longgarkan filternya.
Mengapa tidak ada ETag di respons?
ETag datang bersama respons untuk request tanpa filter. Respons untuk request dengan coin, exchange, min_spread, atau filter lain dibuat khusus untuk request itu dan datang tanpa tag, sehingga If-None-Match tidak berlaku untuk respons tersebut.