Manejo de errores de la API de Hyperliquid: Decodificación de rechazos de órdenes, margen y comprobaciones de oráculo

Respuesta directa: dónde se encuentran los rechazos de órdenes en la API de Hyperliquid

Cuando envías una orden al endpoint firmado /exchange de Hyperliquid, la API no lanza un error HTTP para fallos a nivel de negocio. En su lugar, la respuesta contiene un array order statuses. Cada elemento corresponde a una orden que enviaste; una orden fallida tiene status: "rejected" y una cadena statuses_reason como InsufficientMargin o PriceOutOfBand. Para fallos de envoltura (por ejemplo, solicitud malformada o una prohibición de trading), la respuesta es un objeto JSON con una cadena response como "Order price is above the maximum allowed price for this asset" o un objeto error. Esto está documentado en los documentos de Hyperliquid y es distinto de los errores de límite de tasa HTTP 429 cubiertos en nuestra guía de límites de tasa de la API de Hyperliquid.

La idea clave: debes inspeccionar el estado y la razón de la orden, no solo el código de estado HTTP. Una respuesta 200 puede contener una orden rechazada. Este artículo decodifica las familias de rechazo que encontrarás en producción y te muestra cómo manejarlas programáticamente.

Mecanismo: cómo valida Hyperliquid las órdenes antes de aceptarlas

El motor de emparejamiento de Hyperliquid realiza una serie de comprobaciones antes de que una orden pueda descansar en el libro o ejecutarse. Estas comprobaciones se aplican en el servidor y son independientes de la validación del lado del cliente. El motor evalúa el capital de tu cuenta, las posiciones actuales, el apalancamiento, el interés abierto y el precio del oráculo. Si alguna comprobación falla, la orden se rechaza con una razón específica.

El endpoint de solo lectura /info proporciona el contexto que necesitas para prevalidar: /info/meta devuelve metadatos de activos que incluyen maxLeverage, szDecimals y maxSz; /info/clearinghouseState te da el capital de tu cuenta y un resumen de margen; /info/assetCtxs proporciona el precio actual del oráculo y el interés abierto. El endpoint firmado /exchange aplica entonces las comprobaciones finales de forma atómica.

La documentación de Hyperliquid enumera los códigos de error y las razones en la sección de errores. Integraciones independientes como el SDK de Python de Hyperliquid y ccxt mapean estos a excepciones, pero comprender las cadenas crudas es esencial para una automatización robusta.

Familias de rechazo y su significado

Los clientes de producción ven un puñado de familias de rechazo. Cada una se asigna a una cadena de razón específica o texto de respuesta. La tabla a continuación las resume; las cadenas exactas están documentadas en los documentos de Hyperliquid y pueden evolucionar.

Comprobaciones de margen y capital – InsufficientMargin o InsufficientAccountValue indican que tu cuenta carece del capital o margen suficiente para soportar el nocional de la orden. Esto sucede a menudo cuando aumentas una posición sin agregar fondos, o cuando las pérdidas no realizadas reducen el capital.

Comprobaciones de riesgo y apalancamiento – RiskLimits o MaxPositionSize significan que la orden excedería tu límite de riesgo o el tamaño máximo de posición para el activo. Leverage too high aparece cuando solicitas más apalancamiento que el maxLeverage del activo de /info/meta.

Límites de interés abierto – La razón Cannot increase position when open interest is at cap (o similar) aparece cuando el interés abierto del activo ha alcanzado su límite. Esta es una protección de todo el mercado, no un problema a nivel de cuenta.

Comprobaciones de precio de oráculo – PriceOutOfBand o la cadena de respuesta "Order price is above the maximum allowed price for this asset" indica que tu precio límite está demasiado lejos del precio actual del oráculo. Hyperliquid aplica un desplazamiento máximo para evitar malas ejecuciones.

Salvaguardas de modo de ejecución – PostOnlyWouldTakeLiquidity significa que tu orden de solo publicación habría coincidido con una orden existente, por lo que se rechazó para preservar la intención de solo creador. Las violaciones de solo reducción ocurren cuando una orden aumentaría una posición en lugar de reducirla.

Existe una distinción práctica crucial entre una orden que es rechazada directamente y una que es aceptada pero luego falla. Cuando la API de Hyperliquid devuelve un rechazo, la entrada de estado de la orden en la matriz de respuesta indica que la orden nunca se colocó; cualquier estado de reposo o trabajo existente para esa orden permanece sin cambios. En contraste, un envío exitoso resulta en un estado de 'en reposo' o 'ejecutada', y para órdenes de múltiples patas o ejecuciones parciales, la matriz puede contener múltiples entradas por pata. Por lo tanto, el llamador no debe tratar la matriz como todo o nada: un solo rechazo no implica que otras patas no se hayan ejecutado, y una ejecución parcial no significa que toda la orden fue rechazada. Esta granularidad es esencial para una contabilidad precisa y para decidir si reintentar, cancelar o ajustar las patas restantes.

• Siempre verifica el campo statuses_reason para fallos por orden.
• Para errores de envoltura, analiza la cadena response o el objeto error.
• No confíes en los códigos de estado HTTP; un 200 puede contener una orden rechazada.

Cliente reproducible: captura y decodifica un rechazo

El siguiente script de Python utiliza el SDK oficial de Hyperliquid para enviar una orden con un precio intencionalmente imposible (por ejemplo, 10% por encima del oráculo) para provocar un rechazo PriceOutOfBand. Imprime el estado de la orden, la razón y el código numérico. Reemplaza la clave privada con una clave de testnet y usa la URL de la API de testnet https://api.hyperliquid-testnet.xyz como se describe en los documentos de Hyperliquid.

Este script es seguro porque usa una testnet y un precio imposible, por lo que no hay fondos reales en riesgo. Nunca ejecutes tales pruebas en mainnet con saldos reales.

import json
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from eth_account import Account

# Testnet configuration - replace with your testnet private key
account = Account.from_key('0x...')  # your testnet private key
base_url = 'https://api.hyperliquid-testnet.xyz'
info = Info(base_url, skip_ws=True)
exchange = Exchange(account, base_url)

# Fetch asset metadata and oracle price
meta = info.meta()
asset = 'BTC'
asset_index = next(i for i, a in enumerate(meta['universe']) if a['name'] == asset)
oracle_price = float(info.all_mids()[asset])

# Intentionally impossible price: 10% above oracle
bad_price = round(oracle_price * 1.10, 1)

# Build and submit order
order = {
    "coin": asset,
    "is_buy": True,
    "sz": 0.001,
    "limit_px": bad_price,
    "order_type": {"limit": {"tif": "Gtc"}},
    "reduce_only": False
}
result = exchange.order(order)
print(json.dumps(result, indent=2))

# Expected output (testnet, may vary):
# {
#   "status": "ok",
#   "response": {
#     "type": "order",
#     "data": {
#       "statuses": [
#         {
#           "resting": {"oid": 123456},
#           "status": "rejected",
#           "statuses_reason": "PriceOutOfBand"
#         }
#       ]
#     }
#   }
# }

Tabla de resultados: asigna razones de rechazo a acciones

Usa la tabla a continuación como punto de partida. Las cadenas de razón exactas están documentadas en los documentos de Hyperliquid; verifica contra la versión de tu SDK. Completa la columna 'Observado en tu configuración' cuando ejecutes el cliente.

• | Razón/Respuesta | Familia | Acción recomendada | Observado en tu configuración |
• |---|---|---|---|
• | InsufficientMargin | Margen | Reduce el tamaño o agrega fondos; verifica el capital mediante /info/clearinghouseState | |
• | RiskLimits | Riesgo | Reduce el tamaño de la posición o espera a que se restablezca el límite de riesgo | |
• | Cannot increase position when open interest is at cap | Interés abierto | Cancela y espera; considera un activo diferente | |
• | PriceOutOfBand | Oráculo | Ajusta el precio para que esté dentro de la banda permitida alrededor del oráculo | |
• | PostOnlyWouldTakeLiquidity | Modo de ejecución | Cancela y vuelve a enviar como una orden de mercado o ajusta el precio | |
• | ReduceOnly would increase position | Modo de ejecución | Verifica tu indicador reduce_only y tu posición actual | |

Lista de verificación de fallos/soluciones: manejo de rechazos en producción

Cuando tu bot recibe un rechazo, sigue esta lista de verificación para decidir la próxima acción. El objetivo es evitar reintentos ciegos que podrían amplificar pérdidas o provocar rechazos repetidos.

1. Analiza la razón del rechazo. Extrae statuses_reason de cada estado de orden. Para errores de envoltura, analiza la cadena response.

2. Verifica previamente el margen y el nocional. Antes de enviar, consulta /info/clearinghouseState para confirmar el margen disponible. Compara el nocional de la orden contra tu capital y el maxLeverage del activo de /info/meta.

3. Ajusta a la banda del oráculo. Si obtienes PriceOutOfBand, obtén el precio actual del oráculo de /info/assetCtxs y establece tu precio límite dentro del desplazamiento permitido (por ejemplo, 5% para la mayoría de los activos, pero consulta los documentos).

4. Verifica los indicadores de solo publicación y solo reducción. Si recibes PostOnlyWouldTakeLiquidity, cancela y vuelve a enviar como una orden límite regular o ajusta tu precio al otro lado del diferencial. Para violaciones de solo reducción, verifica tu posición actual y el lado de la orden.

5. Vuelve a enviar con un nuevo precio o cancela. Para rechazos relacionados con el precio, vuelve a enviar con un precio corregido. Para rechazos de margen o riesgo, no reintentes hasta que ajustes tu cuenta o el tamaño de la orden.

6. Registra y alerta. Registra la carga útil completa del rechazo para depuración. Usa registro estructurado para rastrear la frecuencia de rechazo por razón.

Para la robustez en producción, considere una estrategia conservadora de reintento y elevación que evite riesgos innecesarios. Primero, limite su nocional del lado del cliente a la banda de precio de marca actual antes del envío, como se documenta en las pautas de la API de Hyperliquid, para reducir la probabilidad de rechazos por precio fuera de banda. Si aún ocurre un rechazo por precio fuera de banda, cancele cualquier orden en reposo y vuelva a enviar con un precio actualizado dentro de la banda. Para todos los demás rechazos duros (como los relacionados con margen, riesgo o interés abierto), no reintente silenciosamente; en su lugar, mapéelos a una alerta local o registro de errores para revisión manual. Este enfoque asegura que los problemas transitorios se manejen automáticamente mientras que los problemas persistentes se escalen, y se alinea con el comportamiento documentado de Hyperliquid. Verifique estas recomendaciones contra la documentación oficial y sus propias pruebas para adaptarlas a su caso de uso específico.

Limitaciones y compensaciones

Las razones de rechazo de Hyperliquid son legibles pero no se garantiza que sean estables entre actualizaciones de protocolo. Los documentos señalan que los códigos de error pueden cambiar; siempre maneja razones desconocidas con elegancia.

La banda de precio del oráculo no es un porcentaje fijo para todos los activos; puede variar. Verifica meta y assetCtxs para cada activo y no codifiques un desplazamiento universal.

Los límites de interés abierto son dinámicos y pueden cambiar a medida que se abren y cierran posiciones. Un rechazo debido al límite de interés abierto puede ser temporal; un reintento después de un breve retraso podría tener éxito, pero evita reintentos agresivos.

Esta guía se centra en rechazos a nivel de negocio. Para problemas a nivel HTTP como tiempos de espera y límites de tasa, consulta nuestras guías de tiempos de espera de RPC de Hyperliquid y límites de tasa de la API de Hyperliquid.

Próximos pasos: construye una integración robusta

Ahora que comprendes la superficie de rechazo, puedes fortalecer tu bot de trading. Comienza implementando la lógica de verificación previa descrita anteriormente, luego agrega un manejador de rechazos que asigne cada razón a una acción. Usa la testnet para simular varios escenarios: margen insuficiente, solo publicación que tomaría liquidez y precio fuera de banda, para verificar tu manejador.

Para una configuración completa de Hyperliquid, revisa nuestra descripción general de la red Hyperliquid y los endpoints de Hyperliquid (Asistente de RPC) para elegir un endpoint confiable. Si usas flujos WebSocket para actualizaciones en tiempo real, consulta nuestra guía de suscripciones y reconexión de WebSocket de Hyperliquid. Para necesidades de datos históricos, consulta Consulta de datos históricos de mercado de Hyperliquid.

Si estás construyendo en OnFinality, nuestro servicio de API proporciona acceso administrado a Hyperliquid y otras redes. Consulta Precios para planes. Para más guías de solución de problemas, visita el centro de aprendizaje de OnFinality.