- API
- Every status,
Errors
Every status,
and what to do.
Seven statuses cover the token surface. The body always says why, and where it can, what to do next.
| Status | Name | When, and what the body says |
|---|---|---|
400 | Bad request | A parameter is out of bounds or malformed. Numeric query parameters are clamped to their documented range; a missing required field or an unparseable body returns 400 with the reason. |
401 | Unauthorized | No token, a revoked token, or a token for a subscription that is no longer valid. Create or rotate tokens under Account, then API Access. |
403 | Plan required | The endpoint needs a higher plan than the token's subscription. The body carries upgrade_required: true, required_tier and your_tier; each endpoint page states its tier. The same 403 without upgrade_required means the account has no active paid or trial subscription. |
404 | Not found | The path does not exist. The JSON body carries did_you_mean with the nearest documented paths and their docs URLs, plus the index URL. |
424 | Upstream unavailable | The data feed did not answer for this ticker or window. Retry after a few seconds; the platform never returns a 502 for this case because the edge would strip the body. |
429 | Rate limited | Per-token limits of 60 requests a minute, 1,000 an hour and a monthly allowance by plan. Retry-After carries the seconds until the window opens; the X-RateLimit-* headers show the remaining budget on every response. |
503 | Service unavailable | Only the flow endpoint uses this, when the intraday volume feed is down. Retry later. |
Payload shapes
Every error is JSON,
and says what to do.
The envelope never changes: an error string, plus the fields below where they help a client recover.
Shapestoken surface, /api/mcp/data
// 401: no token, revoked, or expired
{"error": "Invalid or revoked token"}
// 403: the endpoint sits above the account's plan
{"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"}
// 403: the account has no active paid or trial subscription
{"error": "API/MCP access requires an active subscription. Subscribe at https://apexvol.com/pricing.",
"tier_required": "basic"}
// 404: unknown path, with the nearest real ones
{"error": "No endpoint at /api/mcp/data/iv_rank/AAPL",
"did_you_mean": ["/api/mcp/data/iv-rank/{ticker}", "/api/mcp/data/iv-crush/{ticker}"],
"docs": "https://apexvol.com/docs/api"}
// 424: the data feed did not answer for this ticker or window
{"error": "No two-sided quote to price the front straddle for XYZ", "upstream": true}
// 429: over the per-token limit; Retry-After header carries the seconds
{"error": "MCP rate limit exceeded: 60 per minute"}
// 429: monthly allowance spent
{"error": "Monthly limit reached (10,000 data requests). Resets on the 1st.",
"budget_exceeded": true, "used": 10000, "limit": 10000, "unit": "data_requests"}
// 500: quote request_id to support
{"error": "Internal error processing this request. It has been logged.", "request_id": "ab12cd34"}
// 503: the intraday volume feed behind options flow is down
{"error": "Options flow data is temporarily unavailable", "data_unavailable": true}Every response, success or error, carries X-RateLimit-Remaining-Minute, X-RateLimit-Remaining-Hour and the monthly budget header, so a client can pace itself before it ever sees a 429. Server errors carry a request_id that matches our logs; quote it to [email protected].
Included with
every paid plan.
From $55 a month, tier-matched: your token queries the data your plan includes and Pro unlocks the full surface.
Real market data, not a sandbox. See it live on AAPL.