Guide

Errors & conventions

How requests and responses are shaped, the status codes you'll see, and the error payloads to handle.

Request & response conventions

GET endpoints take query-string parameters; POST/PUT/PATCH take a JSON body (Content-Type: application/json).
Tickers are case-insensitive (normalized to upper case). Path-style endpoints use /api/<area>/<TICKER>; older chain endpoints use ?ticker=.
Dates are YYYY-MM-DD; times are HH:MM US-Eastern market time.
All responses are JSON. IV values are decimals in chain rows (0.25 = 25%) but percentages in most analytics summaries — descriptions note units where ambiguous. null is used for missing values (never NaN).
MCP data endpoints always wrap as {success: true, data: …} or {success: false, error: '…'}.

HTTP status codes

Code	Meaning	Typical payload
200	Success	Endpoint-specific JSON.
400	Bad request — missing/invalid params, invalid JSON, expired CSRF	`{"error": "…"}` (+ `csrf_expired`)
401	Invalid/expired MCP token (token surface only)	`{"error": "…"}`
402	Quota cap reached (watchlist)	`{limit_reached, limit, tier, upgrade_message}`
403	Demo restriction, insufficient tier (Pro required on the token surface), or account not yet enabled	See payload shapes below.
404	Unknown ticker/resource, no data, or unpublished feature	`{"error": "…"}`
426	apexvol-mcp client below the minimum version (token surface only)	`{"error": "…", "upgrade_required": true}` — reinstall/update the client
429	Rate limit or monthly budget exceeded	`{"error": "…"}` (+ `demo_restricted` or `budget_exceeded`); token surface adds a `Retry-After` header
500	Internal error	`{"error": "…", "request_id": "ab12cd34"}` on the token surface — quote the `request_id` to support and we can find the exact traceback
503	Maintenance, disabled feature, or upstream temporarily unavailable	`{"error": "maintenance" \| message}`; data outages add `data_unavailable: true` (e.g. options flow while the upstream feed lacks intraday volume)

Error payload shapes

JSON

// Tier gate (403) — upgrade required
{
  "error": "upgrade_required",
  "message": "This feature requires PRO plan",
  "required_tier": "pro",
  "current_tier": "basic",
  "upgrade_url": "/pricing"
}

// Demo restriction (403)
{ "error": "Demo mode is limited to AAPL...", "demo_restricted": true }

// Subscription floor (403) — MCP token whose owner has no active paid plan
{ "error": "API/MCP access requires an active subscription — every paid plan includes it, with data access matching your plan tier. Subscribe at https://apexvol.com/pricing.", "tier_required": "basic" }

// Endpoint tier gate (403) — the endpoint's feature sits above your plan.
// Every endpoint enforces the same tier as its web-app twin; the payload
// names the tier you need.
{ "error": "This endpoint requires the Premium plan (your plan: Basic). Upgrade at https://apexvol.com/pricing.", "upgrade_required": true, "required_tier": "premium", "your_tier": "basic" }

// Access gate (403) — MCP token whose owner's account isn't API-enabled yet
{ "error": "API access is invite-only right now. Contact support@apexvol.com to enable yours.", "beta_required": true }

// Maintenance (503)
{ "error": "maintenance", "message": "We are currently upgrading our systems." }

// Data outage (503) — endpoint depends on data the upstream feed can't
// currently provide; other analytics are unaffected
{ "error": "Options flow data is temporarily unavailable: …", "data_unavailable": true }

// Internal error (500) — request_id matches our logs exactly
{ "error": "Internal error processing this request. It has been logged.", "request_id": "ab12cd34" }

← Rate limits Endpoint reference →