Error Codes and Retries
Details
Docs navigation
- Getting started: Quickstart, Authentication, Rate limits, Errors and retries (you are here)
- Guides: Symbol formats, Timestamps and time zones, Pagination, Split and dividend adjustments, WebSocket streaming, Dataset downloads, Excel and Google Sheets, Changelog
- API reference: Stock bars, Stock trades and quotes, Snapshots and movers, Tickers, exchanges, calendar, Splits and dividends, Fundamentals and SEC filings, Options chain and Greeks, Options EOD, bars, OI, Forex, Crypto, Crypto derivatives, Futures bars and continuous, Settlements and COT, Indices, Economic data, Technical indicators
- SDKs: Python, JavaScript
This page lists the API error codes the marketdata.co API returns, what each one means, and which ones you should retry. If a script stops with an exception at 3 a.m., start here. The short version: retry 429 and 5xx with backoff, fix the request for everything in the 400s.
Early access. The API is planned and not live yet. These codes are the v1 design.
Details
The error body
Every error uses HTTP status codes plus a JSON body with a stable, machine-readable code:
{
"status": "error",
"error": {
"code": "invalid_parameter",
"message": "interval must be one of 1s, 1m, 5m, 15m, 30m, 1h, 1d, 1w, 1mo",
"param": "interval",
"request_id": "req_2b81c0de"
}
}
Match on error.code, not on message. Messages can be reworded; codes will not change within v1. param appears when one parameter is to blame.
Code
Error codes
| HTTP | error.code |
Cause | Retry? |
|---|---|---|---|
| 400 | invalid_parameter |
A parameter has the wrong type or value | No, fix the request |
| 400 | missing_parameter |
A required parameter is missing | No |
| 400 | invalid_symbol_format |
Symbol does not match the format for this asset class, e.g. EUR/USD instead of EURUSD |
No |
| 400 | range_too_large |
start to end is too long for one call at this interval |
No, split the range or page through it |
| 400 | invalid_cursor |
The cursor is malformed or from a different query |
No, restart the query |
| 401 | missing_api_key |
No key sent | No |
| 401 | invalid_api_key |
Key wrong or revoked | No |
| 403 | plan_required |
Your plan does not cover this data or history depth | No |
| 403 | commercial_use_required |
Endpoint needs a commercial licence | No |
| 404 | symbol_not_found |
We do not carry this symbol, or it never existed | No |
| 404 | not_found |
Unknown endpoint path | No |
| 429 | rate_limited |
Too many requests in the window | Yes, after Retry-After |
| 500 | internal_error |
Our fault | Yes, with backoff |
| 503 | service_unavailable |
Maintenance or an upstream feed is down | Yes, with backoff |
| 504 | timeout |
The query took too long | Yes, or narrow the range |
Details
A retry pattern
- Retry only 429, 500, 503 and 504.
- On 429, wait the
Retry-Aftervalue. - On 5xx, wait 1, 2, 4, 8 then 16 seconds, plus a little random jitter.
- Give up after five tries and log the
request_id.
Example (Python):
import random
import time
import requests
RETRY = {429, 500, 503, 504}
def call(url, headers, params=None):
for attempt in range(5):
r = requests.get(url, headers=headers, params=params, timeout=30)
if r.status_code not in RETRY:
if not r.ok:
err = r.json()["error"]
raise ValueError(f"{err['code']}: {err['message']} ({err['request_id']})")
return r.json()
delay = float(r.headers.get("Retry-After", 2 ** attempt))
time.sleep(delay + random.random())
raise RuntimeError(f"gave up after 5 tries on {url}")
GET requests are safe to repeat. They never change anything on our side.
Watch out
Notes and gotchas
- An empty
resultslist is not an error. Asking for stock bars on a Saturday returns200withcount: 0. symbol_not_foundon a ticker you know exists usually means a format issue (BRK.B, notBRK-BorBRKB). Check symbol formats.- A delisted stock is not a 404. It returns history up to its last trading day, and the reference endpoint shows a
delist_date. plan_requiredon a long range often means only part of the range is outside your plan. Shortenstartand try again.- Do not retry 401 or 403 in a loop. Those will not fix themselves and they still count against your rate limit.
- On WebSocket connections, errors arrive as messages with
"type": "error"and the samecodevalues. See WebSocket streaming.
Keep reading
Next steps
Details
Was this page useful?
[Yes] [No]
Hit an error that is not on this list? Send it with the request_id through the custom data form.