Códigos de error

#La forma de un error

Todo error tiene una sola forma, sea cual sea la capa que rechaza (pasarela, servicio o validación): status: "error", server_time y un objeto error con un code estable, un message en inglés y, cuando un parámetro es el culpable, param. error.details, un objeto presente cuando el error lleva datos estructurados, da lo mismo para el código: suggestion, accepted, la ventana de tu plan en un history_depth, retry_after_s en los rechazos temporales. Nada va junto a 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"
      ]
    }
  }
}

Los rechazos ligados al plan tienen la misma forma, más error.details.retry_after_s en los rechazos temporales (también en la cabecera Retry-After). La cabecera X-Deny-Reason nombra el motivo: rate_limited, quota_exceeded, plan_family, plan_websocket, missing_api_key, invalid_api_key o 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
    }
  }
}

El 403 de profundidad lleva X-Deny-Reason: history_depth y error.code: history_depth, como los demás rechazos ligados al plan; su mensaje indica el limit máximo utilizable en esa temporalidad. Las ventanas por plan están en la página Límites de uso.

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);
  }
}

#Códigos HTTP

#Indicadores

La validación sigue un orden fijo (timeframe, limit, símbolo, lectura de los indicadores, regla del límite, lectura de las velas), y gana el primer fallo. Un cuerpo corregido puede revelar un segundo error.

#Flujo WebSocket

Toda petición imposible recibe un mensaje op: error que dice lo que se esperaba: la lista de símbolos válidos, la de los canales, los límites de depth. Tres situaciones no producen un error sino un cierre:

La clave se comprueba en el handshake, antes de abrir: una clave ausente recibe un 401 missing_api_key, una desconocida o revocada un 401 invalid_api_key (con WWW-Authenticate), un plan sin el flujo (Free) un 403 plan_websocket — cada vez el valor de X-Deny-Reason. Un 429 indica un ritmo de apertura demasiado alto, y un 503 un servicio de flujo que ha alcanzado su capacidad, para todas las cuentas: reintenta un poco más tarde. Una vez conectado, un canal cuya familia no está en el plan recibe op: error con error.code: plan_family y se rechaza toda la suscripción. Ver Límites de uso.

#Servidor MCP

Los errores siguen un único patrón, Error (HTTP NNN): message [code: …], y una llamada de herramienta fallida se marca como error MCP (isError), con el mismo error en structuredContent.error: status, code, message, y param, hint, retry_after_s cuando aplican. Cada llamada de herramienta se evalúa como una petición REST con la clave del cliente: un 403 por una familia fuera del plan o un 429 por cuota se devuelven tal cual, con su mensaje y su error.code. Dos familias le son propias:

• Petición no válida: un campo desconocido, un objetivo ausente (symbol, asset, series) o que ningún campo pedido espera, un parámetro que la ruta elegida no acepta, un timeframe que ningún campo usa, una ventana fechada sobre un campo que no la admite. Todo se enumera en un solo mensaje, antes de cualquier llamada de red.
• Respuesta parcial: en las cinco herramientas de datos MCP (get_pair_data, get_options_data…), un campo con error no bloquea los demás. Se indica en errors y la respuesta lleva partial: true; la llamada solo falla si ningún campo tiene éxito.

Solo hay reintento si el origen no respondió (502, 503, 504 o fallo de red): un 500 no se repite, porque cada petición cuenta en la cuota del cliente. Un tiempo de espera agotado devuelve Error (HTTP 504) tras treinta segundos.

#Estrategia de reintentos

No todo se puede repetir. Repetir una petición errónea produce exactamente la misma respuesta y consume cuota para nada.

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

• Respeta Retry-After en lugar de inventar un plazo: el servidor sabe cuándo estará listo.
• Limita el número de intentos. Tres o cuatro bastan: más allá, el problema no es pasajero.
• No repitas un 4xx, salvo el 429. Corrige la petición.
• En el flujo, reconéctate con un retraso creciente, y lee el código de cierre: 4003, se alcanzó el límite del plan, otra conexión de la cuenta debe cerrarse primero; 4005 (client too slow), el cliente está sobrecargado, y reconectar sin cambiar el consumo reproducirá el corte. Un 503 en el handshake solo pide esperar.