Public API: Stable Error Codes#
This release only affects you if you use the GammaFlip API — nothing changes in the app.
Improved
- API errors now return stable codes you can safely branch on: Every
/api/v1error now has one shape — a fixed, machine-readable code inerror, and human prose inmessage:{"error": "invalid_exchange", "message": "Exchange 'kraken' is not available."}. Previouslyerrorheld an English sentence like"Authentication required", so the only way to detect a specific failure was matching text that could be reworded at any time. The codes areunauthorized,subscription_required,market_not_in_plan,invalid_exchange,no_dataandrate_limit_exceeded— the same ones our error docs have always promised, but which the API never actually returned. Branch onerror; never parsemessage, its wording can change. Heads-up — this is a breaking change: if your integration matches on the old sentences, it needs updating. If you built against the published docs, it starts working.
Fixed
/expirationsreturned errors disguised as success: An unknown exchange on/api/v1/expirations/...came back wrapped in the normal success envelope, with the error buried insidedata. So the obvious client code —response.json()["error"]— worked on the two/gexendpoints and crashed on this one. All endpoints now return an identical, un-enveloped error body.Retry-Afteron rate-limited responses was unusable: A429carried an ISO-8601 timestamp inRetry-After, where the HTTP standard allows only a number of seconds or an HTTP date — so retry libraries (urllib3, axios-retry) that read it automatically would break. The header is no longer sent at all: the daily quota resets at midnight UTC, so the only honest value could be many hours, and those same libraries would obey it by sleeping through your session. Schedule retries offX-RateLimit-Reset(ISO 8601) instead, as the docs already recommend — it's unchanged.- Undocumented
market_not_in_planerror: The403you get when requesting a market your plan doesn't cover (Crypto vs TradFi) was missing from the published error list. It's now documented, and carriesmarketandcurrent_tieralongside the code.


