API-Fehler

Verwenden Sie die Antwortoberfläche, die zur jeweiligen Anfrage passt:

• HTTP-Fehler: Eine 4xx- oder 5xx-JSON-Antwort enthält stabile code- und diagnostische message-Felder.
• Order-Ergebnis: Eine HTTP-200-Order-Antwort kann dennoch abgelehnt sein. Prüfen Sie deren status und reason.
• JSON-RPC-Antwort: JSON-RPC-Endpunkte behalten numerische error.code-Werte innerhalb einer HTTP-200-Antwort bei.

HTTP-Fehlerantworten

Jede von der API erzeugte HTTP-4xx- und 5xx-JSON-Fehlerantwort enthält:

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

code ist der programmatische Vertrag. Verzweigen Sie anhand dieses kleingeschriebenen Bezeichners und behandeln Sie unbekannte zukünftige Werte sicher. message ist Diagnosetext. Zeigen oder protokollieren Sie ihn, aber parsen Sie ihn nicht.

error ist ein beibehaltenes Legacy-Feld. Einige Endpunkte stellen es bereits bereit und tun dies weiterhin, es ist jedoch opak und nicht der neue Vertrag. Bestehende endpunktspezifische Felder, etwa Readiness-Details und Retry-After, bleiben erhalten.

HEAD-Antworten haben keinen Body. Verwenden Sie deren HTTP-Status wie gewohnt; Hypercall fügt keinen separaten Fehlercode-Header hinzu.

Auszahlungs-Preflight

USDC-Auszahlungen mit Core-Zustellung prüfen die Aktivierung des Empfängers und die Transferkompatibilität, bevor eine neue Auszahlung angenommen wird. Behandeln Sie withdrawal_destination_inactive und withdrawal_destination_mode_unsupported als Zielfehler. withdrawal_preflight_unavailable bedeutet, dass die Verifizierung vorübergehend nicht verfügbar ist. withdrawal_source_unavailable erfordert, dass der Dienst ein kompatibles sendendes Konto oder eine kompatible Route wiederherstellt.

Diese Fehler erzeugen keine neue Auszahlungsbelastung. Eine zuvor angenommene Anfrage behält ihren bestehenden Status. Ein erfolgreicher Preflight garantiert keine Zustellung; überwachen Sie weiterhin den Ausführungsstatus der Auszahlung. Reine EVM-Auszahlungen erfordern keine HyperCore-Kontoberechtigung.

Kontomodus für Portfolio Margin

Portfolio Margin bewertet das Account anhand seines HyperCore-Equity, das HyperCore nur für Accounts im Modus unifiedAccount veröffentlicht.

• POST /margin-mode mit portfolio gibt 400 pm_account_not_unified zurück, wenn sich das Account in einem anderen Modus befindet. Signieren Sie die hl_set_abstraction-Direktive mit der Abstraktion unifiedAccount, warten Sie, bis HyperCore sie bestätigt, und versuchen Sie es dann erneut.
• GET /portfolio für ein Portfolio-Margin-Account ohne aktuelles HyperCore-Equity gibt 409 pm_account_not_unified zurück, wenn HyperCore nie Equity für das Account veröffentlicht hat und es in einem anderen Modus meldet. Andernfalls wird 503 pm_account_equity_pending zurückgegeben, bis ein aktueller Unified-Snapshot die Engine erreicht; ist das beibehaltene Equity veraltet und meldet HyperCore einen anderen Modus, nennt die Meldung diesen Modus. Wiederholen Sie pm_account_equity_pending nach kurzer Zeit und aktivieren Sie den Unified-Modus erneut, wenn die Meldung besagt, dass das Account ihn verlassen hat.
• account_abstraction_unavailable (503) bedeutet, dass der HyperCore-Kontomodus nicht gelesen werden konnte. Versuchen Sie es nach kurzer Zeit erneut.

RFQ-Leg-Größen

Kontraktgrößen werden in Einheiten von 0.000001 ausgeführt. POST /rfq/request lehnt eine Leg-Größe mit mehr als sechs Dezimalstellen mit HTTP 400 ab; die Meldung nennt die größte ausführbare Größe, abgerundet. Hypercall rundet die Größe nicht für Sie, da der Taker die exakten Leg-Größen signiert. Runden Sie vor dem Signieren ab und reichen Sie erneut ein.

Gründe für RFQ-Quote-Preflight

Ein im Preflight abgelehntes Maker-Quote enthält einen kurzen Grundcode. margin_rejected bedeutet, dass das Konto des Makers die Margin-Prüfung für das Paket nicht bestanden hat. pricing_unavailable bedeutet, dass der Handelsplatz das Paket nicht bewerten konnte, beispielsweise weil eine Oberfläche der impliziten Volatilität oder ein Referenzpreis fehlt; dies ist keine Margin-Entscheidung, und ein neues Quote kann erfolgreich sein, sobald die Preisbildung wiederhergestellt ist.

Order-Ablehnungen

Eine Order kann HTTP 200 mit einem abgelehnten Ausführungsergebnis zurückgeben:

{
  "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 ist erläuternder Text, kein stabiler Code. Er kann Live-Werte enthalten und sich ändern, wenn sich die Validierung weiterentwickelt. Bei unzureichender Portfolio Margin ist required die gesamte Initial Margin nach der Order, während die Felder current_consumed_* und incremental_order_* die bestehende Nutzung von der neuen Order trennen. Verwenden Sie status, um eine abgelehnte Order zu erkennen, und zeigen oder protokollieren Sie dann reason. Ein stabiler Vertrag für Order-Ablehnungscodes wäre separate Protokoll- und SDK-Arbeit.

Für Perpetual-Orders mit Portfolio Margin ist open_orders_initial_margin die zusätzliche IM aus dem ungünstigsten unabhängig wählbaren Zustand (ungefüllt oder vollständige Limit-Ausführung) über alle Live-Orders. Eine Order kann angenommen werden, während das Konto unter der IM liegt, nur wenn ihr Hinzufügen weder diese Hülle noch die entsprechende Maintenance-Kapazitätsanforderung bei ungünstigster Ausführung erhöht. Offene Orders ändern weiterhin nicht die veröffentlichte Positions-MM. Clients dürfen aus einer Annahme nicht schließen, dass das aktuelle Konto vollständig finanziert ist, und dürfen den diagnostischen reason nicht parsen, um zwischen finanzierter und nicht verschlechternder Zulassung zu unterscheiden.

JSON-RPC-Fehler

GET /orderbook behält bei einem fehlenden Instrument seine Antwort im JSON-RPC-Stil mit HTTP 200 bei:

{
  "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
}

Verzweigen Sie anhand des numerischen error.code. RSM-spezifische JSON-RPC-Codes sind nicht Teil des standardmäßigen öffentlichen HTTP-Katalogs.

Öffentlicher Fehlercode-Katalog

Dieser durchsuchbare Katalog wird aus der Erweiterung info.x-hypercall-error-codes im öffentlichen OpenAPI-Dokument generiert. Er enthält nur verbraucherseitige HTTP-Codes und stets aktive JSON-RPC-Codes.

Loading API error catalog…

Checkliste zur Behandlung

• HTTP-Clients: Verzweigen Sie anhand von code, bewahren Sie den HTTP-Status und beachten Sie Retry-After, sofern vorhanden.
• Order-Clients: Behandeln Sie status: "REJECTED" als Ausführungsergebnis, auch wenn die HTTP-Anfrage erfolgreich war.
• JSON-RPC-Clients: Verzweigen Sie anhand des numerischen error.code für das native Protokoll des Endpunkts.
• Alle Clients: Halten Sie einen sicheren Fallback für unbekannte zukünftige Codes bereit und parsen Sie niemals Diagnosemeldungen.