Early access is open. Free sample datasets are live now. Download a sample

Error Codes and Retries

Details

Docs navigation

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

  1. Retry only 429, 500, 503 and 504.
  2. On 429, wait the Retry-After value.
  3. On 5xx, wait 1, 2, 4, 8 then 16 seconds, plus a little random jitter.
  4. 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 results list is not an error. Asking for stock bars on a Saturday returns 200 with count: 0.
  • symbol_not_found on a ticker you know exists usually means a format issue (BRK.B, not BRK-B or BRKB). 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_required on a long range often means only part of the range is outside your plan. Shorten start and 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 same code values. 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.