Códigos de error

#La forma de un error

El detalle lo lleva la clave detail. En los errores de validación, nombra el valor erróneo y, cuando existe una lista finita, la enumera.

{
  "detail": "Symbole 'PEPEUSDT' inconnu. Valeurs acceptees : BTCUSDT, ETHUSDT, ..."
}

Los rechazos ligados al plan tienen una forma fija, definida por la pasarela: status, timestamp y detail, más retry_after en los rechazos temporales (también presente en la cabecera Retry-After). La cabecera X-Deny-Reason nombra el motivo: rate, quota, family, websocket o key.

{
  "status": "error",
  "timestamp": 1775648290510,
  "detail": "Debit depasse : votre offre autorise un nombre limite de requetes par minute.",
  "retry_after": 1
}

El 403 de profundidad lo devuelve la propia ruta, sin X-Deny-Reason: su detail siempre empieza por « Profondeur d’historique hors offre » e indica el limit máximo utilizable en esa temporalidad. Las ventanas por plan están en la página Límites de uso.

#Códigos HTTP

#Indicadores

La validación sigue un orden fijo (temporalidad, número de resultados, símbolo, análisis de los indicadores, regla del límite, lectura de las velas), y gana el primer fallo. Un cuerpo corregido puede por tanto 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 la apertura: una clave ausente o inválida, o un plan sin el flujo (Free), recibe un 403 en el handshake, con X-Deny-Reason key o websocket. Un 429 en ese momento indica un ritmo de apertura demasiado alto. Una vez conectado, un canal cuya familia no está en el plan recibe op: error (« canal … hors offre : la famille … n’est pas incluse dans votre abonnement ») y se rechaza toda la suscripción. Ver Límites de uso.

#Servidor MCP

Los errores siguen un único patrón, Erreur (HTTP NNN) : message, para que un agente solo tenga un caso que reconocer. 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 detail. Dos familias le son propias:

• Métrica desconocida: el mensaje enumera las cuarenta y seis métricas válidas.
• Selección no válida: dos objetivos a la vez, objetivo ausente, objetivo equivocado o un objetivo pasado a una métrica de todo el mercado. El error nombra el parámetro esperado y se produce antes de cualquier llamada de red.

Un fallo del servidor provoca un reintento automático antes de notificarse. Un tiempo de espera agotado devuelve Erreur (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.

def should_retry(code: int) -> bool:
    """What is transient, and what never will be."""
    # 429 and 503 will pass: the server says when.
    if code in (429, 503):
        return True
    # 500: a fault on the service side, a retry makes sense.
    if code == 500:
        return True
    # 400, 403, 422: the request is at fault. Replaying it as is will
    # produce 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 plazo creciente, y trata un cierre 4003 como señal de sobrecarga en el cliente: reconectarte sin cambiar el consumo reproducirá el corte.