Error reference

Your request was malformed — bad query parameter, invalid header, unsupported value.

Common causes

• Missing required header (e.g. X-Idempotency-Key on mutating account endpoints)
• Out-of-range parameter (e.g. dte=999 when range is 0–365)
• Invalid ticker format (we expect uppercase, no special chars)
• Header value exceeds length limit

Fix

Read detail; it names the offending parameter. Validate against reference before retrying.

Missing, malformed, or unrecognized API key.

Common causes

• No Authorization header at all
• Header doesn't start with Bearer  (with space)
• Key doesn't start with gxb_live_
• Key is a typo / partial copy
• Key was rotated (regenerate) and you're using the old one

Fix

Verify the header shape: Authorization: Bearer gxb_live_<key>. If your key was regenerated, use the new one from the modal you saw at regen time. If you don't have a key on record, mint one at /account.

Returned only by the /api/account/api-key/purchase endpoint when the proration invoice fails to charge. Stripe rejected the card and we rolled back the SubscriptionItem.

Common causes

• Card declined (insufficient funds, fraud rule, expired)
• 3D Secure / SCA challenge required and not completed
• Card not on file (misconfigured Stripe customer)

Fix

Update payment method via Stripe Customer Portal (linked from /account), then retry. No charge was made on the failed attempt; the SubscriptionItem was rolled back.

Authenticated but not allowed. Either the endpoint requires a higher tier than your key has, or the resource (ticker) isn't in your tier's whitelist.

Common causes

• Pro key calling /api/v1/greeks or /api/v1/premium-map (Trader-only)
• Ticker not in your plan's whitelist (Starter has 10 tickers, Pro has 30)
• Add-on canceled but key not yet revoked at our end (rare timing window)

Fix

For tier-gated endpoints: upgrade to Trader at /account. For ticker access: check the tier matrix.

Route doesn't exist or the requested resource has no data.

Common causes

• Typo in URL (/api/v1/radar vs /api/v1/Radar)
• Calling the legacy /api/... path with a Bearer key (only /api/v1/... accepts Bearer)
• Asking for a ticker we don't ingest

Fix

Verify the URL. Use /api/v1/<resource> for API-key auth. Check supported tickers on /pricing or in reference.

Your key was permanently revoked — either by you (regenerate or cancel-addon) or by us (security suspension).

Common causes

• You ran Regenerate — the OLD key is now revoked. Use the new one from the modal.
• You ran Cancel addon — the addon SubscriptionItem was removed; key was revoked by webhook.
• Your 1-hour undo window after a manual revoke expired and the key auto-promoted to revoked.
• We suspended the key for terms-of-use violation per API Terms.

Fix

Visit /account. If the addon is still active and you just lost the key, click Regenerate and capture the new key in the modal. If the addon was canceled and you want it back, click Add API Access again.

You crossed your tier's per-minute or per-day cap. The response includes a Retry-After header (seconds to wait).

Common causes

• Polling tighter than 1 req/sec on Pro
• Multi-ticker burst at the same second-of-minute
• Pro daily cap exhausted (50,000 requests / UTC day)
• Distributed key sharing across many machines

Fix

Honor Retry-After. Implement exponential backoff as fallback. See rate-limits for a copy-paste retry helper.

Something broke on our end. These should be rare; we monitor them.

Fix

Don't retry inline — use exponential backoff (start 2s, double, cap at 60s, give up after 5 attempts). If 500s persist for one ticker, try a different ticker to isolate. Email contact@gexboard.com if it lasts more than a few minutes.

Upstream issue: our market data provider, our database, or the gateway. Usually transient.

Fix

Same as 500 — back off exponentially. If you see sustained 503s, our service is genuinely down; check gexboard.com/status. Avoid retrying inside a tight loop — it makes recovery slower for everyone.