- API
- Errors & conventions
Guide
Errors and
conventions.
How requests and responses are shaped, the status codes you will see, and where to find the payload for each. Units and bases have their own page.
Request and response conventions
- GET endpoints take query-string parameters; POST endpoints take a JSON body with
Content-Type: application/json. - Tickers are case-insensitive and normalised to upper case. Path-style endpoints use
/api/mcp/data/<area>/<TICKER>. - Dates are
YYYY-MM-DD; times areHH:MMUS Eastern market time. - All responses are JSON, wrapped as
{"success": true, "data": …}or{"success": false, "error": "…"}.nullmarks a missing value, never NaN. - Implied volatility is annualised percentage points on every summary endpoint (34.43 means 34.43%) and decimals in chain rows; every payload that carries IV says which with
iv_units. The full list of units and bases is on the conventions page. - Numeric parameters are clamped to their documented range; a missing required field or an unparseable body answers 400 with the reason.
HTTP status codes
| Code | Meaning | Typical payload |
|---|---|---|
| 200 | Success | Endpoint-specific JSON inside the envelope. |
| 400 | Bad request: a missing required field or an unparseable body. | {"error": "…"} |
| 401 | No token, a revoked token, or an expired one. | {"error": "…"} |
| 403 | An endpoint above the account's plan, an account without an active plan, or an account without API access. | {"error": "…", "upgrade_required": true, "required_tier": "…", "your_tier": "…"}, {"tier_required": "basic"} or {"beta_required": true}. |
| 404 | Unknown path or ticker, or an unpublished feature. An unknown path also lists the nearest real endpoints. | {"error": "No endpoint at …", "did_you_mean": [...], "docs": "…"} |
| 424 | The request was valid but the analytic could not be produced from upstream data: no two-sided quote to price, a history the feed does not carry, or a vendor outage. | {"error": "…", "upstream": true}. The message says what was missing. Retry later; this is never a client bug. |
| 426 | The apexvol-mcp client is below the minimum version. | {"error": "…", "upgrade_required": true}. Reinstall or update the client. |
| 429 | Rate limit or monthly allowance exceeded. | {"error": "…"} or {"budget_exceeded": true, "used": …, "limit": …}, plus a Retry-After header. |
| 500 | Internal error. | {"error": "…", "request_id": "ab12cd34"}. Quote the request id to support and we can find the exact traceback. |
| 503 | The upstream feed behind an analytic is down. Today only options flow does this, when the volume feed reports nothing at all. Also maintenance mode. | {"error": "…", "data_unavailable": true} or {"error": "maintenance"}. |
Every status with its full payload shape, on one page: the errors reference. Each endpoint page lists the statuses it can return.
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.