Error codes

#The shape of an error

Every error has one shape, whatever the layer that refused (gateway, service or validation): status: "error", server_time and an error object with a stable code, an English message and, when one parameter is at fault, param. error.details, an object present when the error carries structured data, gives the same things for code: suggestion, accepted, your plan's window on a history_depth, retry_after_s on time-based refusals. Nothing sits next to error.

{
  "status": "error",
  "server_time": "2026-09-30T16:07:27.808Z",
  "error": {
    "code": "invalid_symbol",
    "message": "Unknown symbol 'BTCUSD'. Did you mean 'BTCUSDT'? Accepted values: ADAUSDT, AVAXUSDT, BNBUSDT, BTCUSDT, DOGEUSDT, ETHUSDT, GRAMUSDT, HBARUSDT, HYPEUSDT, LINKUSDT, LTCUSDT, NEARUSDT, SOLUSDT, SUIUSDT, TAOUSDT, TRXUSDT, UNIUSDT, USDCUSDT, USDTUSDC, XLMUSDT, XMRUSDT, XRPUSDT.",
    "param": "symbol",
    "details": {
      "suggestion": "BTCUSDT",
      "accepted": [
        "ADAUSDT",
        "AVAXUSDT",
        "BNBUSDT",
        "BTCUSDT",
        "DOGEUSDT",
        "ETHUSDT",
        "GRAMUSDT",
        "HBARUSDT",
        "HYPEUSDT",
        "LINKUSDT",
        "LTCUSDT",
        "NEARUSDT",
        "SOLUSDT",
        "SUIUSDT",
        "TAOUSDT",
        "TRXUSDT",
        "UNIUSDT",
        "USDCUSDT",
        "USDTUSDC",
        "XLMUSDT",
        "XMRUSDT",
        "XRPUSDT"
      ]
    }
  }
}

Refusals tied to the plan have the same shape, plus error.details.retry_after_s on time-based refusals (also in the Retry-After header). The X-Deny-Reason header names the reason: rate_limited, quota_exceeded, plan_family, plan_websocket, missing_api_key, invalid_api_key or history_depth.

{
  "status": "error",
  "server_time": "2026-09-30T16:07:27.808Z",
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: your plan allows a limited number of requests per minute. Retry after the Retry-After delay.",
    "details": {
      "retry_after_s": 2
    }
  }
}

The depth 403 carries X-Deny-Reason: history_depth and error.code: history_depth, like the other refusals tied to the plan; its message gives the maximum usable limit on that timeframe. The windows per plan are on the Usage limits page.

const response = await fetch(url, { headers: { "X-API-KEY": key } });
const body = await response.json();

if (body.status === "error") {
  switch (body.error.code) {
    case "rate_limited":
    case "service_unavailable":
      // Transient: wait Retry-After seconds, then retry.
      break;
    case "history_depth":
      // Ask for less history, or upgrade: error.message gives the max limit.
      break;
    case "invalid_symbol":
    case "unknown_parameter":
      // Fix the request: error.param names the culprit, error.message the fix.
      break;
    default:
      throw new Error(body.error.code + ": " + body.error.message);
  }
}

#HTTP codes

#Indicators

Validation follows a fixed order (timeframe, limit, symbol, parsing of the indicators, ceiling rule, reading of the candles), and the first failure wins. A corrected body can therefore reveal a second error.

#WebSocket stream

Every impossible request receives an op: error message that says what was expected: the list of valid symbols, that of the channels, the bounds of depth. Three situations produce not an error but a closure:

The key is checked at the handshake, before the opening: a missing key receives a 401 missing_api_key, an unknown or revoked one a 401 invalid_api_key (with WWW-Authenticate), a plan without the stream (Free) a 403 plan_websocket — the value of X-Deny-Reason each time. A 429 there signals too high an opening rate, and a 503 a stream service that has reached its capacity, all accounts together: retry a little later. Once connected, a channel whose family is not in the plan receives op: error with error.code: plan_family and the whole subscription is refused. See Usage limits.

#MCP server

The errors follow a single pattern, Error (HTTP NNN): message [code: …], and a failed tool call is flagged as an MCP error (isError), with the same error in structuredContent.error: status, code, message, and param, hint, retry_after_s when they apply. Every tool call is judged as a REST request with the client’s key: a 403 for a family outside the plan or a 429 for quota come back as they are, with their message and their error.code. Two families are specific to it:

• Invalid request: an unknown field, a missing target (symbol, asset, series) or one that no requested field expects, a parameter the chosen route does not accept, a timeframe that no field uses, a dated window on a field that has none. Everything is listed in a single message, before any network call.
• Partial response: in the five MCP data tools (get_pair_data, get_options_data…), a field in error does not block the others. It is reported under errors and the response carries partial: true; the call itself only fails when no field succeeds.

A retry only happens when the upstream did not answer (502, 503, 504 or a network failure): a 500 is not replayed, because every request counts against the client’s quota. A timeout returns Error (HTTP 504) after thirty seconds.

#Retry strategy

Not everything can be replayed. Replaying a faulty request produces exactly the same response, and consumes quota for nothing.

import httpx  # pip install httpx


def should_retry(response: httpx.Response) -> bool:
    """What is transient, and what never will be (the official SDKs do the same)."""
    # A spent monthly quota only resets on the 1st of the month: fail fast.
    if response.status_code == 429 and response.headers.get("X-Deny-Reason") == "quota_exceeded":
        return False
    # 429 (rate) and 503: the server says when, in Retry-After. 502 and 504:
    # a gateway hiccup or a slow query. Retry with an increasing delay.
    if response.status_code in (429, 502, 503, 504):
        return True
    # 500: a fault on the service side, retry once.
    if response.status_code == 500:
        return True
    # 401, 403, 404, 405, 422: the request is at fault. Replaying it as is
    # produces exactly the same response.
    return False

• Respect Retry-After rather than inventing a delay: the server knows when it will be ready.
• Bound the number of attempts. Three or four are enough: beyond that, the problem is not transient.
• Do not replay a 4xx, 429 aside. Correct the request.
• On the stream, reconnect with an increasing delay, and read the close code: 4003, the ceiling of the plan is reached, another connection of the account has to close first; 4005 (client too slow), the client is overloaded, and reconnecting without changing the consumption will reproduce the cut. A 503 at the handshake only asks you to wait.