Errors - Binibit Labs

HTTP status codes

Status	Meaning
`200 OK`	Request succeeded.
`400 Bad Request`	Missing or invalid query parameter.
`404 Not Found`	Unknown ticker_id, asset, or path.
`429 Too Many Requests`	Rate limit exceeded.
`500 Internal Server Error`	Transient server-side error — retry.
`503 Service Unavailable`	Maintenance window or overload — retry later.

Error envelope

Non-2xx responses include a JSON body:

{
  "code": "INVALID_PARAM",
  "message": "ticker_id is required",
  "field": "ticker_id"
}

Field	Type	Description
`code`	string	Machine-readable error code (see table below).
`message`	string	Human-readable description.
`field`	string \| null	The query parameter or field that triggered the error, when applicable.

Error codes

Code	HTTP	Meaning
`INVALID_PARAM`	400	A query parameter is missing, malformed, or out of range.
`NOT_FOUND`	404	The requested ticker_id, asset, or path does not exist.
`RATE_LIMIT`	429	Per-IP rate limit exceeded. See `Retry-After` header.
`INTERNAL`	500	Unexpected server error. Safe to retry with backoff.
`UNAVAILABLE`	503	Service is temporarily down for maintenance. See `Retry-After` if present.

Retry strategy

HTTP	Retry?	Strategy
4xx (except 429)	No	Fix the request.
429	Yes	Honor `Retry-After`.
500	Yes	Exponential backoff with jitter, max 5 attempts.
503	Yes	Honor `Retry-After`, longer backoff.

import time, random, requests

def fetch_with_retry(url, max_attempts=5):
    for attempt in range(max_attempts):
        r = requests.get(url, timeout=10)
        if r.status_code == 200:
            return r.json()
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "1")))
            continue
        if 500 <= r.status_code < 600:
            time.sleep((2 ** attempt) + random.random())
            continue
        r.raise_for_status()
    raise RuntimeError(f"Exhausted retries for {url}")