Genesis API responses and errors: JSON format, ETag and 304, HTTP codes
In short
- A successful Genesis API response is an envelope of
success,dataandmeta; an error issuccess: falseplus anerrorobject with a code and a message. - Sending the previous ETag in
If-None-Matchreturns304with no body when the data has not changed, and a 304 costs no quota. - Retry
429and503after theRetry-Afterpause. A retry will not fix400,401,403,404or410— change the request, the key or the plan.
Genesis API answers every request in JSON, a text data format built from key–value objects and arrays. A successful response always comes in the same envelope of success, data and meta; an error comes with an HTTP status code and an error object. The status code tells your program what to do next: use the data, wait Retry-After seconds and retry, or fix the request.
Response envelope: success, data and meta
A shortened GET /arbitrage/spot-spot response from the documentation (the endpoint is available on every plan):
{
"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 | Type | Contents |
|---|---|---|
success | boolean | true — the request succeeded, false — an error |
data | array or object | The endpoint's data |
meta.count | int | Number of items in data |
meta.updated_at | int | Unix time the data was built |
meta.freshness_sec | int | Serving delay for your plan, seconds |
meta.plan | string | Your plan, pro in the example |
The exception is funding analytics: its meta carries count, updated_at and schema_version, with no freshness_sec or plan. The envelope is described in the Response format section of the documentation, and the data fields on each endpoint's page.
Three conventions apply to every endpoint:
- an empty value is
null: for example,max_position_usdin DEX – Futures isnullwhen the exchange does not provide a position limit; - spreads and rates are percentages:
"spread_pct": 0.92means 0.92%, not 92%; - timestamps are unix seconds:
1783802410is July 11, 2026, 20:40:10 UTC; dates sent as strings, such aspool_created_atin Cross-chain, have the string type in the documentation.
data: an array of rows or an object
The shape of data is stated in each endpoint's description. For GET /arbitrage/spot-spot it is an array: one item per arbitrage pair, like a row of the table on the site. For GET /account/usage it is a single object with the state of your key:
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 is available on every plan and shows your plan, quota usage and freshness_sec: polling more often than that gains nothing. The fields are described in Usage, and the first request is walked through in the quick start. Code that works with several endpoints should check the shape explicitly: isinstance(data, list) in Python.
Filters: optional, full dataset without them
All filter parameters are optional: a request without them returns the endpoint's full dataset. List several exchanges in exchange separated by commas, and set a coin by its ticker in 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"
The -G flag turns the -d parameters into a query string: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Spell exchange names the way they come back in response fields: ByBit, Gate, MEXC. Arbitrage endpoint parameters are in the arbitrage endpoints guide.
The quota counts responses, not rows: a request with or without filters is one call. A filter shrinks the response body, and with it the traffic and the download-limit usage. All limits are covered in the Genesis API limits guide.
gzip compression
Genesis API sends full datasets and large responses gzip-compressed when the client sends the Accept-Encoding: gzip header (RFC 9110, section 12.5.3). A small response may arrive uncompressed.
Python requests sends that header itself and decompresses the response. curl does not ask for compression without the --compressed flag; with the flag, it asks and decompresses.
The download limit counts compressed data: at most 60 MB per 10 seconds per key, and responses under 64 KB are not counted. Over the limit you get 429 download_limited.
ETag and 304: skip unchanged data
ETag is a response header with a version tag of the data. The client sends that tag back in the If-None-Match header. If the data has not changed, the server answers 304 Not Modified with no body; if it has, a regular 200 with new data and a new ETag.
# Full dataset, no filters: print the response headers only
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
# Repeat with the ETag from the first response (illustrative value)
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"'
An ETag comes with the response to a request without filters and changes with every new data snapshot. A response to a filtered request is built for that request and comes without an ETag; there the filter itself saves the traffic. ETags help most on slow-moving data: the funding analytics summary changes its ETag roughly every 15 minutes, and 304 replies do not count toward its full-download limit.
A 304 response uses no quota but counts toward the requests-per-second limit. Send the tag back exactly as it arrived: under RFC 9110 it is a quoted string, and the W/ prefix marks a weak tag.
Error codes and what to do
On an error, Genesis API returns the matching HTTP status and a body with success: false:
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Requests per second limit exceeded."
}
}
error.code is a machine-readable code your program can branch on. error.message is the explanation for a human: for 400 it gives the reason, for 410 the replacement address.
| HTTP | error.code | Meaning | What to do |
|---|---|---|---|
400 | bad_request | Invalid request parameters, for example volume=700 on /orderbooks/exec | Fix the parameters per message: the same request will fail again |
401 | invalid_key | Key missing, invalid or revoked, or the API subscription expired | Check the X-API-Key header and the subscription status in your profile |
403 | plan_restricted | The endpoint is not in your plan | Move to a plan that includes it or drop the request |
404 | not_found | Endpoint or resource not found: dataset, section, coin, order book | Check the path and parameters against the documentation |
410 | gone | The endpoint is retired | Switch to the address given in message |
429 | rate_limited | Requests-per-second limit exceeded, or the period quota is used up | Wait Retry-After seconds and slow down; if the quota is used up, wait for the reset or upgrade the plan |
429 | download_limited | Download volume exceeded: 60 MB of compressed data per 10 s per key | Wait Retry-After, cut traffic with filters, coin and If-None-Match |
500 | internal_error | Internal error | Retry later; if it persists, contact support with the X-Request-Id |
503 | snapshot_not_ready | Data is being rebuilt or its source is restarting | Retry after Retry-After seconds |
The Retry-After header comes with 429 and 503 and holds the number of seconds to wait: usually a few seconds, but when the period quota is used up it is the time until the quota resets, which can be days. 4xx and 5xx errors use no quota but count toward the requests-per-second limit, so an early retry will most likely return the same error. Glossary terms: HTTP 429 and rate limit.
X-Request-Id: what to send to support
Every Genesis API response, successful or not, carries an X-Request-Id header with the request's identifier. If an error keeps coming back or the data looks wrong, send support:
- the
X-Request-Idvalue; - the request time in UTC;
- the endpoint with its parameters, for example
GET /arbitrage/spot-spot?coin=BTC; - the HTTP status and
error.code.
Do not send your key. If it ended up in a chat, logs or code that other people can see, reissue it in your profile: the old key stops working immediately.
Response handling order
Check the status code
200— readdataandmeta, and store the ETag if one came.304— use the data from the previous response.Handle temporary errors
429and503with a short pause — waitRetry-Afterseconds and retry, at most three times in a row.500— retry later.Stop on request errors
400,401,403,404,410, and a429with a pause of hours or days — fix the parameters, the key or the plan, or wait for the quota reset.Check the data age
Compare
meta.updated_atwith the current time: a bot acting on an old snapshot sees spreads that are already gone.Schedule the next request
No sooner than
meta.freshness_secseconds later, withIf-None-Matchfor requests without filters.
A get_json function in Python
The function puts these rules together: it keeps the last ETag for each address and returns the previous data on 304, waits Retry-After on 429 and 503 and retries up to three times, but does not wait out pauses longer than a minute. Other errors raise an exception with the status, the message and the X-Request-Id. The key comes from the GENESIS_API_KEY environment variable.
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): # one request plus up to 3 retries
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] # the data has not changed
wait = float(r.headers.get("Retry-After", 1))
if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
time.sleep(wait) # never wait out hours or days
continue
try:
body = r.json()
except ValueError:
raise GenesisError(r.status_code, "not 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: # only on responses without filters
cache[key] = (r.headers["ETag"], body["data"])
return body["data"]
The timeout=15 parameter is a must: without a timeout, requests waits for a response forever.
Polling at your plan's interval: the full dataset comes with an ETag, and rows are filtered in code. 4xx errors stop the program; a server failure waits for the next cycle.
pause = get_json("/account/usage")["freshness_sec"]
while True:
try:
rows = get_json("/arbitrage/spot-spot") # full dataset
top = [x for x in rows if x["spread_pct"] >= 1]
print(len(top), "pairs with a spread of 1% or more")
except GenesisError as e:
if e.status < 500:
raise # 4xx: the request, key, plan or quota
print("server error, retrying next cycle:", e)
time.sleep(pause)
Questions and answers
Does a 304 response use quota?
No. Only 200 responses use quota. 304 responses and 4xx and 5xx errors are free but count toward the requests-per-second limit.
What should I do after a 410 ?
The endpoint is retired, and the replacement address is in error.message. For example, GET /arbitrage/predictions was retired on November 15, 2026, and its message points to /predictions/arbitrage. Update the path in your code.
Why is data empty when there is no error?
The filters removed every row: for example, min_spread is above every current spread. Such a response has meta.count equal to 0, so relax the filter.
Why is there no ETag in the response?
An ETag comes with the response to a request without filters. A response to a request with coin, exchange, min_spread or another filter is built for that request and comes without a tag, so If-None-Match does not apply to it.