Errors

Errors take two forms depending on transport — a JSON body on REST and a typed frame on WebSocket — but share the same stable error code strings. Key your retry logic off code / error; treat message as opaque since its wording may change.

---

REST errors

{ "error": "<code>", "message": "<human readable>", "retryAfter": 30, "detail": {} }

retryAfter (seconds) is present only on 429 rate_limited. detail is optional and varies by endpoint.

HTTP status codes

Status	Use
200	Success
400	Validation failed — bad input shape or out-of-range parameters
401	Missing, malformed, or expired JWT
403	Authenticated, but tier or role is insufficient
404	Resource not found
409	Conflict (username already taken on register)
429	Rate limited
500	Server error or upstream failure

REST error codes

HTTP	error code	Endpoint(s)	Meaning
400	invalid_address	/api/auth/nonce, /api/auth/wallet, /v1/history/rates/:address	Address is not 0x + 40 hex
400	invalid_signature	/api/auth/wallet	Signature length wrong or recovery doesn’t match address
400	invalid_time	/v1/history/*	from or to couldn’t be parsed
400	invalid_limit	/v1/history/*	limit outside [1, 10000]
400	invalid_cursor	/v1/history/*	Cursor base64 decode failed
400	validation_error	various	Generic validation failure — see message
401	unauthorized	JWT-gated routes	Missing or expired JWT
401	invalid_credentials	/api/auth/login	Wrong password
401	nonce_expired	/api/auth/wallet	Nonce TTL elapsed or already consumed
403	lookback_too_far_for_tier	/v1/history/*	Requested window exceeds the caller’s tier limit (free = 1 day)
403	insufficient_tier	/api/apikeys POST	Tier < api; API key issuance requires a paid subscription
403	forbidden	role-gated routes	Caller role insufficient
404	not_found	various	Resource doesn’t exist or isn’t yours
409	username_taken	/api/auth/register	Username already exists
429	rate_limited	rate-limited routes	Wait retryAfter seconds, then retry
500	db_error	/v1/history/*	TimescaleDB query failed
500	internal_error	anywhere	Catch-all server bug; safe to retry once with backoff

---

WebSocket errors

{ "type": "error", "code": "<code>", "message": "<human readable>", "retryAfter": 7 }

The connection remains open after most WS errors. The exception is auth_failed / auth_error, which the server may follow with a close frame — reconnect after refreshing credentials.

WebSocket error codes

code	Trigger	Recovery
rate_limited	Subscribe rate exceeded (30 actions per 10-second window)	Wait retryAfter seconds, then retry the subscribe.
symbol_limit_reached	Per-session tier symbol cap hit (free = 3, paid = 100)	Unsubscribe an existing symbol, or upgrade tier.
free_tier_cap_reached	Free-tier per-IP / per-userId cap (3) exceeded across all sessions	Unsubscribe in another session, or authenticate with an API key.
subscription_required	Subscribed to a role-gated venue (e.g. arbflag without super_admin)	Cannot upgrade by retrying; do not retry.
auth_error / auth_failed	Bad API key on {action:"auth"}, or expired JWT on subscribe	Refresh credentials; reconnect.
invalid_symbol / unknown_symbol	Symbol unknown to that venue	Fix the symbol string; consult GET /v1/symbols/{venue}/live for the canonical list.
internal_error	Server-side fault	Retry with exponential backoff.

---

Retry decision matrix

Error category	Retry?
429 rate_limited / WS rate_limited	Yes — after retryAfter seconds
400 validation_error, invalid_*	No — the request is wrong; fix before retrying
401 unauthorized / invalid_credentials	No — refresh credentials first, then retry
403 insufficient_tier / forbidden / subscription_required	No — upgrade tier or role; same request will keep failing
404 not_found	No — resource doesn’t exist
500 internal_error / db_error	Yes — exponential backoff (start 1 s, double, cap at 30 s); surface after 5 failures

Python retry sketch

import time, httpx

def get_with_retry(url, headers=None, max_attempts=5):
    delay = 1.0
    for attempt in range(max_attempts):
        r = httpx.get(url, headers=headers or {})
        if r.status_code == 200:
            return r.json()
        body = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
        code = body.get("error", "")
        if r.status_code == 429:
            wait = body.get("retryAfter", delay)
            time.sleep(wait)
            continue
        if r.status_code in (400, 401, 403, 404):
            raise ValueError(f"Non-retryable error {r.status_code}: {code}")
        if r.status_code >= 500:
            if attempt < max_attempts - 1:
                time.sleep(delay)
                delay = min(delay * 2, 30)
                continue
        raise RuntimeError(f"Request failed: {r.status_code} {code}")
    raise RuntimeError("Max retry attempts exceeded")