Errores

Cada fallo tiene la misma forma:

{
  "error": {
    "code": "ACCOUNT_EXECUTING",
    "message": "An order is in flight. Stopping now would leave its outcome unknown.",
    "details": []
  },
  "requestId": "3f8a1c92-7b4e-4d81-a2f6-0c5e9b3d7a14"
}

Compara por code. Es estable entre versiones. message está escrito para una persona y va a cambiar (y está en inglés). details aparece en los fallos de validación y nombra los campos; en una orden fallida, details[0] lleva su orderId, su state y retryable.

requestId está en cada respuesta de error y queda registrado en cada fila de auditoría. Inclúyelo en una solicitud de soporte y se puede encontrar la llamada completa.

Los códigosCopiar el enlace

Autenticación y autorizaciónCopiar el enlace

Un solo código para cada fallo de autenticación es intencional: distinguir "clave desconocida" de "secreto incorrecto" permitiría a alguien con una lista de claves candidatas separar las reales de las falsas. Consulta Autenticación.

Inicio de sesión de MCPCopiar el enlace

/mcp y /mcp/insights responden a la solicitud de una app conectada con un desafío WWW-Authenticate en lugar de uno de los códigos anteriores:

Consulta Servidor MCP para ver qué provoca cada una.

SolicitudesCopiar el enlace

ACCOUNT_NOT_FOUND también es lo que recibes para una cuenta que existe pero pertenece a otra persona. Responder 403 confirmaría que un id adivinado es real. POST /v1/accounts/{id}/password, POST /v1/accounts/{id}/server y DELETE /v1/accounts/{id} responden a una cuenta inexistente con NOT_FOUND en lugar de ACCOUNT_NOT_FOUND; trata ambos igual.

Límites de frecuenciaCopiar el enlace

Los límites son por workspace y por clase de trabajo, así que las consultas repetidas nunca gastan el margen que necesitan tus órdenes. Cada uno es una tasa constante por minuto más una ráfaga corta.

Cada respuesta nombra su clase en x-ratelimit-class y el tope en x-ratelimit-limit. Las sesiones de la consola tienen sus propios límites.

CuentasCopiar el enlace

TradingCopiar el enlace

422 en lugar de 400 para un rechazo: la solicitud estaba bien formada y la entendimos. El broker la rechazó, que es un problema distinto con una solución distinta.

ORDER_UNRESOLVED es el que hay que manejar con cuidado. Consulta Trading e historial.

PlanesCopiar el enlace

FacturaciónCopiar el enlace

InstrumentosCopiar el enlace

Órdenes multicuentaCopiar el enlace

Copy tradingCopiar el enlace

Ninguno de estos se puede reintentar tal como se envió: cada uno nombra algo de la estrategia, la suscripción o la cuenta que la propia solicitud debe cambiar primero.

Hooks de alertas de TradingViewCopiar el enlace

La URL del hook los devuelve a TradingView, y quedan registrados en el log del hook.

Webhooks y eventosCopiar el enlace

Consola, claves y miembrosCopiar el enlace

El inicio de sesión en sí (/auth, que usa la consola) responde con su propia forma, { code, message }:

Ciclo de vidaCopiar el enlace

NEEDS_OPERATOR merece énfasis. No lo reintentes, y no lo metas en un bucle con backoff. Los inicios de sesión fallidos repetidos son la forma en que un broker bloquea una cuenta, y en ese punto corregir la contraseña ya no basta. Muéstraselo a quien sea dueño de las credenciales.

ReintentarCopiar el enlace

Decide por code, no por estado. Reintenta 500, y un 503 cuyo code no sea ORDER_UNRESOLVED, con backoff exponencial y jitter. Nunca reintentes ORDER_UNRESOLVED: consulta la orden. No reintentes 4xx, salvo 429 después de su retry-after; nada más de la solicitud habrá mejorado. Tampoco reintentes 501 CAPABILITY_UNAVAILABLE: la respuesta solo cambia cuando se actualiza la terminal de la cuenta.

Por qué 503 y no 502. Cada fallo que es nuestro y no tuyo —SEND_FAILED, ORDER_UNRESOLVED, SCHEDULER_FAILED, RESTART_FAILED, PROVIDER_ERROR— responde 503 con el cuerpo JSON. Hasta el 3 de octubre de 2026 eran 502, y la capa de red frente a la API reemplazaba el cuerpo de cada 502 con su propio texto, así que un cliente no podía distinguir un reenvío seguro de uno que nunca debe ocurrir. Si ramificabas según 502, ramifica según code.

import random, time

def retryable(response):
    if response.status_code == 500:
        return True
    if response.status_code == 503:
        # SEND_FAILED is proven never to have reached the broker. ORDER_UNRESOLVED
        # may have executed: poll the order, never resend.
        return response.json().get("error", {}).get("code") != "ORDER_UNRESOLVED"
    return False

def call_with_retry(send, attempts=5):
    # For an order, `send` must carry the same Idempotency-Key on every attempt.
    for attempt in range(attempts):
        response = send()
        if not retryable(response):
            return response
        if attempt == attempts - 1:
            return response
        # Jitter, not a fixed schedule: every client backing off in lockstep
        # arrives together and reproduces the load that caused the failure.
        time.sleep(min(2 ** attempt, 30) * (0.5 + random.random()))
    raise AssertionError("unreachable")

En una orden, send debe llevar el mismo Idempotency-Key en cada intento; y el jitter evita que todos los clientes que esperan al mismo ritmo vuelvan juntos y reproduzcan la carga que causó el fallo.

Incluso un ORDER_UNRESOLVED reintentado es inofensivo cuando lleva el mismo Idempotency-Key: la clave sigue reclamada y vuelve la misma respuesta. Lo que nunca debe ocurrir es un reenvío con una clave nueva.

Los 503 del ciclo de vida —SCHEDULER_FAILED, RESTART_FAILED— no involucran ninguna orden y también se pueden reintentar con backoff sin riesgo.

warm (poner en línea) se puede reintentar tal cual sin riesgo: una segunda llamada a una cuenta que ya está en línea devuelve alreadyRunning: true.

Enviar órdenes no es seguro de reintentar a ciegas. Envía un Idempotency-Key con cada orden: un reintento con la misma clave devuelve el primer resultado en lugar de abrir una segunda operación. Reintentar sin una es el único lugar de esta API donde un reintento descuidado cuesta dinero.

Cuando el error es el estado, no el código HTTPCopiar el enlace

Un 202 de warm significa que aceptamos el trabajo, no que tuvo éxito. El inicio de sesión todavía puede fallar después, y lo informa a través del estado de la cuenta, no de un código HTTP que ya nadie está escuchando.

Consulta GET /v1/accounts/{id}/status y trata invalid_credentials, needs_2fa, needs_certificate y trading_disabled como fallos. Cuentas y ciclo de vida tiene un bucle de consulta que maneja esto correctamente.