Errores y Motivos de Rechazo

Catálogo completo de códigos de error y motivos de rechazo.

Formato de Respuesta de Error

Respuestas de Error HTTP (Middleware)

Errores JSON estructurados del middleware (HTTP 4xx/5xx):

{
  "error": "<code>",
  "message": "<human message>"
}

Rechazos a Nivel de Motor (HTTP 200)

Los rechazos de trading devuelven HTTP 200 con OrderUpdateMessage.status = "REJECTED":

{
  "timestamp": 1735000000000,
  "info": { ... },
  "status": "REJECTED",
  "reason": "<exact rejection string>",
  "filled_size": 0,
  "order_id": null,
  "wallet_address": "0x...",
  "mmp_triggered": false
}

Crítico: No dependa de los códigos de estado HTTP para los rechazos de trading. Verifique siempre los campos status y reason.

Códigos de Error del Middleware

Estos se devuelven como respuestas de error HTTP con cuerpo JSON estructurado.

Código	Estado HTTP	Descripción
invalid_request	400	No se puede leer el cuerpo de la solicitud
invalid_json	400	Falló el parseo del JSON
missing_field	400	Falta un campo obligatorio
invalid_wallet	400	No se pudo parsear la cadena de la wallet
invalid_parameter	400	Parámetro inválido (p. ej., size/price debe ser string)
signature_verification_failed	400	Falló la recuperación de la firma EIP-712
unsupported_endpoint	400	El middleware no soporta esta ruta
unauthorized	401	El firmante no está autorizado para la wallet (falló la autenticación del agente)
internal_error	500	La verificación de autorización del agente falló inesperadamente

Motivos de Rechazo del Motor

Estos aparecen en OrderUpdateMessage.reason cuando status="REJECTED".

Instrumento Vencido

Motivo: "Instrument has expired"

Causa: Se colocó una orden sobre un instrumento que ya ha vencido.

Acción: Verifique el vencimiento del instrumento vía GET /instruments o GET /markets.

Cuenta Sin Fondos

Motivo: "Account has no funds. Please deposit before trading."

Causa: El saldo en efectivo de la cuenta es <= 0.0.

Acción: Deposite USDC en la wallet antes de operar.

Margen Insuficiente

Motivo: "Insufficient margin: required={:.2}, available={:.2}, shortfall={:.2}"

Ejemplo: "Insufficient margin: required=1500.00, available=1200.00, shortfall=300.00"

Causa: La verificación de margen previa a la operación encontró que el colateral disponible (equity) es insuficiente para cubrir el requisito de margen después de la orden propuesta.

Para cuentas de Margen Estándar, el colateral requerido depende del lado de la opción, el tipo de opción, el strike, el precio del activo subyacente y el portafolio actual. Consulte Margen Estándar para conocer el modelo de margen vigente en el lanzamiento.

Acción:

1. Verifique el portafolio vía GET /portfolio?wallet=...
2. Revise el cálculo de margen en Margen
3. Reduzca el tamaño de la posición o agregue colateral

Precio Spot Faltante

Motivo: "Failed to get portfolio: No spot price available for underlying: {underlying}"

Causa: El motor no puede inferir el precio spot del activo subyacente necesario para simular ejecuciones.

Acción: Verifique la conectividad del feed de precios spot de Hyperliquid. Los precios spot provienen del feed WebSocket allMids.

Restricciones de Nivel (Tier)

Motivo: "Tier1 users cannot go short. Filled long position: {filled}, total sell orders (including new): {total} (symbol: {symbol})"

Causa: La wallet es tier1 (solo posiciones largas) e intentó vender sin una posición larga ejecutada suficiente.

Acción:

1. Verifique el tier vía GET /user-tier?wallet=...
2. Asegúrese de que todas las ventas estén cubiertas por posiciones largas ejecutadas
3. Contacte a Hypercall si necesita acceso de emisor (writer) para una integración de market maker

Símbolo Inválido

Motivo: "Invalid symbol: {symbol}"

Causa: No existe un libro de órdenes para el símbolo.

Acción:

1. Verifique que el mercado exista vía GET /instrument-specs y GET /markets
2. Verifique el formato del símbolo: UNDERLYING-YYYYMMDD-STRIKE-(C|P)

Error de Parseo del Símbolo

Motivo: "Failed to parse symbol: {detail}"

Causa: El símbolo no coincide con el formato esperado.

Acción: Verifique que el formato del símbolo coincida con UNDERLYING-EXPIRY-STRIKE-(C|P) o el estilo Deribit DDMMMYY.

Fallos de Cancelación

Orden No Encontrada

Motivo: "Order not found for cancellation: {client_id}"

Causa: No se encontró la orden con el client_id dado.

Acción: Verifique que el client_id sea correcto y que la orden exista vía GET /orders?wallet=....

Libro de Órdenes No Encontrado

Motivo: "Orderbook not found for symbol: {symbol}"

Causa: No existe un libro de órdenes para el símbolo.

Acción: Verifique que el símbolo sea válido y que el mercado exista.

Orden No Presente en el Libro de Órdenes

Motivo: "Order {id} not found in orderbook {symbol}"

Causa: El ID de la orden existe pero la orden no está en el libro de órdenes (puede haber sido ejecutada/cancelada).

Acción: Verifique el estado de la orden vía GET /orders?wallet=....

Orden Ya Ejecutada

Motivo: "Order {id} is already filled and cannot be cancelled"

Causa: La orden fue ejecutada por completo antes de la solicitud de cancelación.

Acción: Verifique el estado de la orden vía GET /orders?wallet=....

Orden Ya Cancelada

Motivo: "Order {id} was already cancelled"

Causa: La orden ya fue cancelada.

Acción: Verifique el estado de la orden vía GET /orders?wallet=....

Validación de Órdenes de Perpetuos

Motivo: "Perp order missing underlying symbol"

Causa: La orden de perpetuo no incluye el campo underlying.

Acción: Asegúrese de que la orden de perpetuo incluya el símbolo underlying.

MMP Activado

Motivo: "MMP triggered during fill processing"

Causa: Se superaron los límites del MMP durante el procesamiento de ejecuciones. La orden fue ejecutada parcialmente, luego se activó el MMP y se canceló la cantidad restante.

Acción:

1. Verifique la configuración del MMP vía GET /mmp-config?wallet=...&currency=...
2. Revise las métricas de la ventana de ejecución
3. Ajuste los límites del MMP o restablezca el estado del MMP vía POST /mmp-config/reset

Consulte MMP para conocer la semántica completa del MMP.

Cancelación por MMP (Otras Órdenes)

Motivo: "Order canceled by MMP trigger"

Causa: La orden fue cancelada porque otra orden de la misma combinación wallet+activo subyacente activó el MMP.

Acción: Revise la configuración del MMP y la actividad de ejecuciones.

Errores de Validación a Nivel de Handler

Estos devuelven HTTP 400 antes de llegar al motor.

Validación de Precio

Error: "Price validation failed: Price {price} has {n} significant figures, maximum allowed is 5"

Causa: El precio excede 5 cifras significativas.

Acción: Redondee el precio a ≤ 5 cifras significativas.

Formato de Tamaño/Precio

Error: "Size must be greater than 0" o "Price must be greater than 0"

Causa: El tamaño o el precio es <= 0 o no puede parsearse como float.

Acción: Asegúrese de que size y price sean números positivos válidos (como strings).

Formato de Símbolo Inválido

Error: HTTP 400 con mensaje de error del handler

Causa: El símbolo no se parsea como un símbolo de opción válido.

Acción: Verifique el formato del símbolo: UNDERLYING-YYYYMMDD-STRIKE-(C|P).

Errores de Órdenes en Lote

Los endpoints de lote devuelven errores por elemento en BulkOrderResult.error:

• "Signature verification failed: ..."
• "Unauthorized: signer not authorized for wallet"
• "Price validation failed: ..."
• "Size must be greater than 0"
• "Price must be greater than 0"
• "Failed to send order to engine"
• "No response from engine"

Cada resultado incluye index (posición en el array de la solicitud) y el booleano success.

Errores de WebSocket

Mensajes de control de WebSocket:

{
  "type": "Error",
  "message": "Authentication required for this channel"
}

Errores comunes:

• "Authentication required for this channel": Intentó suscribirse a un canal privado sin ?wallet=
• "Client not found": Error interno (conexión perdida)

Mejores Prácticas para el Manejo de Errores

1. Verifique siempre el campo status: No dependa de los códigos de estado HTTP para los rechazos de trading
2. Parsee la cadena reason: Utilice las cadenas exactas de motivo para el manejo programático
3. Maneje los errores en lote: Verifique BulkOrderResult.error para cada elemento en solicitudes en lote
4. Lógica de reintentos: No reintente órdenes con estado REJECTED (corrija primero el problema subyacente)
5. Registro de logs: Registre el OrderUpdateMessage completo para depurar rechazos

Tabla de Referencia de Códigos de Error

Motivo de Rechazo	Categoría	Estado HTTP	Acción
Instrument has expired	Vencimiento	200	Verifique el vencimiento, use otro instrumento
Account has no funds...	Fondos	200	Deposite fondos (cuando esté implementado)
Insufficient margin: ...	Margen	200	Reduzca el tamaño, agregue colateral, verifique el portafolio
Failed to get portfolio: No spot price...	Datos	200	Verifique la conectividad del feed de Hyperliquid
Tier1 users cannot go short...	Tier	200	Suba a tier2 o cubra las ventas
Invalid symbol: ...	Símbolo	200	Verifique que el mercado exista
Order not found for cancellation: ...	Cancelación	200	Verifique que la orden exista
Order {id} is already filled...	Cancelación	200	La orden ya fue ejecutada
Order {id} was already cancelled	Cancelación	200	La orden ya fue cancelada
MMP triggered during fill processing	MMP	200	Revise la configuración del MMP, ajuste los límites
Order canceled by MMP trigger	MMP	200	Revise la configuración del MMP, ajuste los límites
signature_verification_failed	Autenticación	400	Verifique la firma, la codificación de strings
unauthorized	Autenticación	401	Apruebe el agente o firme con la wallet
Price validation failed: ...	Validación	400	Redondee el precio a ≤ 5 cifras significativas

Depuración de Rechazos

1. Verifique los detalles de la orden: Verifique que symbol, price, size y side sean correctos
2. Verifique el portafolio: GET /portfolio?wallet=... para ver las posiciones actuales y el efectivo
3. Verifique el tier: GET /user-tier?wallet=... para verificar las restricciones de tier
4. Verifique el MMP: GET /mmp-config?wallet=...&currency=... para revisar los límites del MMP
5. Verifique el mercado: GET /markets y GET /instruments para verificar que el instrumento exista
6. Revise los logs: Los logs del servidor pueden contener contexto adicional (no expuesto vía API)

Referencias

• Lógica de rechazo: aplicada en el motor de trading
• Verificaciones de margen: aplicadas antes de la admisión de la orden
• Verificaciones de tier: aplicadas según el tier de cada wallet
• Validación del handler: validación estándar de solicitudes