Errores de la API

Use la superficie de respuesta que corresponda a la solicitud:

• Fallo HTTP: una respuesta JSON 4xx o 5xx tiene campos estables code y de diagnóstico message.
• Resultado de orden: una respuesta de orden HTTP 200 aún puede ser rechazada. Revise sus campos status y reason.
• Respuesta JSON-RPC: los endpoints JSON-RPC conservan valores numéricos de error.code dentro de una respuesta HTTP 200.

Respuestas de error HTTP

Toda respuesta de error JSON HTTP 4xx y 5xx generada por la API incluye:

{
  "error": "existing endpoint value, when present",
  "code": "invalid_field",
  "message": "price must be greater than zero"
}

code es el contrato programático. Ramifique su lógica según este identificador en minúsculas y maneje de forma segura valores futuros desconocidos. message es texto de diagnóstico. Muéstrelo o regístrelo, pero no lo analice.

error es un campo heredado que se conserva. Algunos endpoints ya lo exponen y lo seguirán haciendo, pero es opaco y no forma parte del nuevo contrato. Los campos existentes específicos de cada endpoint, como los detalles de disponibilidad y Retry-After, se mantienen.

Las respuestas HEAD no tienen cuerpo. Use su estado HTTP normalmente; Hypercall no agrega un encabezado separado con el código de error.

Verificación previa de retiros

Los retiros de USDC con entrega en Core verifican la activación del destinatario y la compatibilidad de la transferencia antes de aceptar un nuevo retiro. Trate withdrawal_destination_inactive y withdrawal_destination_mode_unsupported como errores de destino. withdrawal_preflight_unavailable significa que la verificación no está disponible temporalmente. withdrawal_source_unavailable requiere que el servicio restablezca una cuenta o ruta de envío compatible.

Estos errores no generan un nuevo débito de retiro. Una solicitud aceptada previamente conserva su estado actual. Una verificación previa exitosa no garantiza la entrega; siga monitoreando el estado de ejecución del retiro. Los retiros solo en EVM no requieren elegibilidad de cuenta en HyperCore.

Modo de cuenta de margen de cartera

El margen de cartera valora la Account a partir de su equity en HyperCore, que HyperCore publica solo para Accounts en modo unifiedAccount.

• POST /margin-mode con portfolio devuelve 400 pm_account_not_unified cuando la Account está en otro modo. Firme la directiva hl_set_abstraction con la abstracción unifiedAccount, espere a que HyperCore la confirme y vuelva a intentarlo.
• GET /portfolio para una Account con margen de cartera sin equity actual en HyperCore devuelve 409 pm_account_not_unified cuando HyperCore nunca ha publicado equity para la Account y la reporta en otro modo. En caso contrario, devuelve 503 pm_account_equity_pending hasta que un snapshot unificado actual llegue al motor; cuando el equity retenido está desactualizado y HyperCore reporta otro modo, el mensaje indica ese modo. Reintente pm_account_equity_pending en breve y vuelva a habilitar el modo unificado si el mensaje indica que la Account salió de él.
• account_abstraction_unavailable (503) significa que no se pudo leer el modo de cuenta de HyperCore. Reintente en breve.

Tamaños de patas de RFQ

Los tamaños de contrato se ejecutan en unidades de 0.000001. POST /rfq/request rechaza un tamaño de pata con más de seis decimales con HTTP 400; el mensaje indica el mayor tamaño ejecutable, redondeado hacia abajo. Hypercall no redondea el tamaño por usted, porque el taker firma los tamaños exactos de las patas. Redondee hacia abajo antes de firmar y vuelva a enviar.

Motivos de verificación previa de cotizaciones RFQ

Una cotización de maker rechazada durante la verificación previa incluye un código de motivo breve. margin_rejected significa que la cuenta del maker no superó la verificación de margen para el paquete. pricing_unavailable significa que el venue no pudo valorar el paquete, por ejemplo porque falta una superficie de volatilidad implícita o un precio de referencia; no es una decisión de margen, y una nueva cotización puede tener éxito una vez que se recupere la valoración.

Rechazos de órdenes

Una orden puede devolver HTTP 200 con un resultado de ejecución rechazado:

{
  "status": "REJECTED",
  "reason": "Insufficient margin: required=1500.00, equity=1200.00, shortfall=300.00, current_consumed_initial_margin=900.00, incremental_order_initial_margin=600.00, current_consumed_maintenance_margin=500.00, incremental_order_maintenance_margin=250.00"
}

reason es texto explicativo, no un código estable. Puede incluir valores en tiempo real y cambiar a medida que evoluciona la validación. Para margen de cartera insuficiente, required es el margen inicial total posterior a la orden, mientras que los campos current_consumed_* e incremental_order_* separan el uso existente de la nueva orden. Use status para identificar una orden rechazada y luego muestre o registre reason. Un contrato de códigos estables de rechazo de órdenes sería un trabajo separado de protocolo y SDK.

Para órdenes de perpetuos con margen de cartera, open_orders_initial_margin es el IM adicional del peor estado seleccionable de forma independiente, sin ejecutar o con ejecución completa al límite, entre las órdenes vivas. Una orden puede aceptarse mientras la cuenta está por debajo del IM solo cuando agregarla no aumenta esa envolvente ni el requisito de capacidad de mantenimiento correspondiente al peor escenario de ejecución. Las órdenes abiertas siguen sin cambiar el MM de posición publicado. Los clientes no deben inferir que la aceptación significa que la cuenta actual está completamente financiada, y no deben analizar el reason de diagnóstico para distinguir una admisión financiada de una admisión que no empeora la posición.

Errores JSON-RPC

GET /orderbook conserva su respuesta de estilo JSON-RPC para un instrumento inexistente, con HTTP 200:

{
  "jsonrpc": "2.0",
  "error": {
    "code": 13020,
    "message": "not_found",
    "data": {"object": "instrument_name", "value": "BTC-20200101-1-C"}
  },
  "testnet": false,
  "usDiff": 1,
  "usIn": 1791273938274109,
  "usOut": 1791273938274109
}

Ramifique según el valor numérico de error.code. Los códigos JSON-RPC específicos de RSM no forman parte del catálogo HTTP público predeterminado.

Catálogo público de códigos de error

Este catálogo con búsqueda se genera a partir de la extensión info.x-hypercall-error-codes del documento OpenAPI público. Contiene únicamente códigos HTTP orientados al consumidor y códigos JSON-RPC siempre activos.

Loading API error catalog…

Lista de verificación de manejo

• Clientes HTTP: ramifique según code, conserve el estado HTTP y respete Retry-After cuando esté presente.
• Clientes de órdenes: trate status: "REJECTED" como un resultado de ejecución aunque la solicitud HTTP haya tenido éxito.
• Clientes JSON-RPC: ramifique según el valor numérico de error.code para el protocolo nativo del endpoint.
• Todos los clientes: mantenga una alternativa segura para códigos futuros desconocidos y nunca analice los mensajes de diagnóstico.