Fehler & Ablehnungsgründe

Vollständiger Katalog der Fehlercodes und Ablehnungsgründe.

Format der Fehlerantworten

HTTP-Fehlerantworten (Middleware)

Strukturierte JSON-Fehler von der Middleware (HTTP 4xx/5xx):

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

Ablehnungen auf Engine-Ebene (HTTP 200)

Trading-Ablehnungen liefern HTTP 200 mit OrderUpdateMessage.status = "REJECTED":

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

Wichtig: Verlassen Sie sich bei Trading-Ablehnungen nicht auf HTTP-Statuscodes. Prüfen Sie immer die Felder status und reason.

Middleware-Fehlercodes

Diese werden als HTTP-Fehlerantworten mit strukturiertem JSON-Body zurückgegeben.

Code	HTTP-Status	Beschreibung
invalid_request	400	Request-Body kann nicht gelesen werden
invalid_json	400	JSON-Parsing fehlgeschlagen
missing_field	400	Pflichtfeld fehlt
invalid_wallet	400	Wallet-String konnte nicht geparst werden
invalid_parameter	400	Ungültiger Parameter (z. B. size/price muss ein String sein)
signature_verification_failed	400	EIP-712-Signaturwiederherstellung fehlgeschlagen
unsupported_endpoint	400	Die Middleware unterstützt diesen Pfad nicht
unauthorized	401	Signer ist für die Wallet nicht autorisiert (Agent-Authentifizierung fehlgeschlagen)
internal_error	500	Agent-Autorisierungsprüfung ist unerwartet fehlgeschlagen

Ablehnungsgründe der Engine

Diese erscheinen in OrderUpdateMessage.reason, wenn status="REJECTED".

Abgelaufenes Instrument

Grund: "Instrument has expired"

Ursache: Order auf ein Instrument platziert, das bereits verfallen ist.

Maßnahme: Prüfen Sie den Verfall des Instruments über GET /instruments oder GET /markets.

Nicht kapitalisiertes Konto

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

Ursache: Das Cash-Guthaben des Kontos ist <= 0.0.

Maßnahme: Zahlen Sie vor dem Handel USDC auf die Wallet ein.

Unzureichende Margin

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

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

Ursache: Die Pre-Trade-Margin-Prüfung hat festgestellt, dass die verfügbaren Sicherheiten (Equity) nicht ausreichen, um die Margin-Anforderung nach der vorgeschlagenen Order zu decken.

Bei Standard-Margin-Konten hängen die erforderlichen Sicherheiten von der Optionsseite, dem Optionstyp, dem Ausübungspreis, dem Preis des Basiswerts und dem aktuellen Portfolio ab. Siehe Standard Margin für das aktuelle Margin-Modell zum Launch.

Maßnahme:

1. Prüfen Sie das Portfolio über GET /portfolio?wallet=...
2. Überprüfen Sie die Margin-Berechnung unter Margin
3. Reduzieren Sie die Positionsgröße oder fügen Sie Sicherheiten hinzu

Fehlender Spot-Preis

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

Ursache: Die Engine kann den Spot-Preis für den Basiswert, der für die Simulation von Fills benötigt wird, nicht ableiten.

Maßnahme: Prüfen Sie die Konnektivität des Hyperliquid-Spot-Preis-Feeds. Spot-Preise stammen aus dem allMids-WebSocket-Feed.

Tier-Beschränkungen

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

Ursache: Die Wallet ist tier1 (nur Long) und hat versucht zu verkaufen, ohne über eine ausreichende gefüllte Long-Position zu verfügen.

Maßnahme:

1. Prüfen Sie das Tier über GET /user-tier?wallet=...
2. Stellen Sie sicher, dass alle Verkäufe durch gefüllte Long-Positionen gedeckt sind
3. Kontaktieren Sie Hypercall, wenn Sie Writer-Zugriff für eine Market-Maker-Integration benötigen

Ungültiges Symbol

Grund: "Invalid symbol: {symbol}"

Ursache: Für das Symbol existiert kein Orderbuch.

Maßnahme:

1. Überprüfen Sie über GET /instrument-specs und GET /markets, ob der Markt existiert
2. Prüfen Sie das Symbolformat: UNDERLYING-YYYYMMDD-STRIKE-(C|P)

Symbol-Parsing-Fehler

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

Ursache: Das Symbol entspricht nicht dem erwarteten Format.

Maßnahme: Überprüfen Sie, ob das Symbolformat UNDERLYING-EXPIRY-STRIKE-(C|P) oder dem Deribit-Stil DDMMMYY entspricht.

Fehlgeschlagene Stornierungen

Order nicht gefunden

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

Ursache: Die Order mit der angegebenen client_id wurde nicht gefunden.

Maßnahme: Überprüfen Sie, ob die client_id korrekt ist und die Order über GET /orders?wallet=... existiert.

Orderbuch nicht gefunden

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

Ursache: Für das Symbol existiert kein Orderbuch.

Maßnahme: Überprüfen Sie, ob das Symbol gültig ist und der Markt existiert.

Order nicht im Orderbuch

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

Ursache: Die Order-ID existiert, aber die Order befindet sich nicht im Orderbuch (möglicherweise gefüllt/storniert).

Maßnahme: Prüfen Sie den Order-Status über GET /orders?wallet=....

Order bereits gefüllt

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

Ursache: Die Order wurde vor der Stornierungsanfrage vollständig gefüllt.

Maßnahme: Prüfen Sie den Order-Status über GET /orders?wallet=....

Order bereits storniert

Grund: "Order {id} was already cancelled"

Ursache: Die Order wurde bereits storniert.

Maßnahme: Prüfen Sie den Order-Status über GET /orders?wallet=....

Validierung von Perp-Orders

Grund: "Perp order missing underlying symbol"

Ursache: Die Perp-Order enthält kein underlying-Feld.

Maßnahme: Stellen Sie sicher, dass die Perp-Order das underlying-Symbol enthält.

MMP ausgelöst

Grund: "MMP triggered during fill processing"

Ursache: MMP-Limits wurden während der Fill-Verarbeitung überschritten. Die Order wurde teilweise gefüllt, dann wurde MMP ausgelöst und die verbleibende Menge storniert.

Maßnahme:

1. Prüfen Sie die MMP-Konfiguration über GET /mmp-config?wallet=...&currency=...
2. Überprüfen Sie die Metriken des Fill-Fensters
3. Passen Sie die MMP-Limits an oder setzen Sie den MMP-Status über POST /mmp-config/reset zurück

Siehe MMP für die vollständige MMP-Semantik.

MMP-Stornierung (andere Orders)

Grund: "Order canceled by MMP trigger"

Ursache: Die Order wurde storniert, weil eine andere Order für dieselbe Kombination aus Wallet und Basiswert MMP ausgelöst hat.

Maßnahme: Überprüfen Sie die MMP-Konfiguration und die Fill-Aktivität.

Validierungsfehler auf Handler-Ebene

Diese liefern HTTP 400 zurück, bevor die Engine erreicht wird.

Preisvalidierung

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

Ursache: Der Preis überschreitet 5 signifikante Stellen.

Maßnahme: Runden Sie den Preis auf ≤ 5 signifikante Stellen.

Größen-/Preisformat

Fehler: "Size must be greater than 0" oder "Price must be greater than 0"

Ursache: Größe oder Preis ist <= 0 oder kann nicht als Float geparst werden.

Maßnahme: Stellen Sie sicher, dass size und price gültige positive Zahlen (als Strings) sind.

Ungültiges Symbolformat

Fehler: HTTP 400 mit Handler-Fehlermeldung

Ursache: Das Symbol lässt sich nicht als gültiges Optionssymbol parsen.

Maßnahme: Überprüfen Sie das Symbolformat: UNDERLYING-YYYYMMDD-STRIKE-(C|P).

Fehler bei Bulk-Orders

Bulk-Endpunkte geben Fehler pro Element in BulkOrderResult.error zurück:

• "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"

Jedes Ergebnis enthält index (Position im Request-Array) und einen success-Boolean.

WebSocket-Fehler

WebSocket-Steuernachrichten:

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

Häufige Fehler:

• "Authentication required for this channel": Versuch, einen privaten Kanal ohne ?wallet= zu abonnieren
• "Client not found": Interner Fehler (Verbindung verloren)

Best Practices für die Fehlerbehandlung

1. Prüfen Sie immer das status-Feld: Verlassen Sie sich bei Trading-Ablehnungen nicht auf HTTP-Statuscodes
2. Parsen Sie den reason-String: Verwenden Sie die exakten Reason-Strings für die programmatische Verarbeitung
3. Behandeln Sie Bulk-Fehler: Prüfen Sie BulkOrderResult.error für jedes Element in Bulk-Requests
4. Retry-Logik: Wiederholen Sie keine REJECTED-Orders (beheben Sie zuerst das zugrunde liegende Problem)
5. Logging: Protokollieren Sie die vollständige OrderUpdateMessage zur Fehleranalyse von Ablehnungen

Referenztabelle der Fehlercodes

Ablehnungsgrund	Kategorie	HTTP-Status	Maßnahme
Instrument has expired	Verfall	200	Verfall prüfen, anderes Instrument verwenden
Account has no funds...	Kapitalisierung	200	Guthaben einzahlen (sobald implementiert)
Insufficient margin: ...	Margin	200	Größe reduzieren, Sicherheiten hinzufügen, Portfolio prüfen
Failed to get portfolio: No spot price...	Daten	200	Konnektivität des Hyperliquid-Feeds prüfen
Tier1 users cannot go short...	Tier	200	Auf Tier2 upgraden oder Verkäufe decken
Invalid symbol: ...	Symbol	200	Prüfen, ob der Markt existiert
Order not found for cancellation: ...	Stornierung	200	Prüfen, ob die Order existiert
Order {id} is already filled...	Stornierung	200	Order bereits ausgeführt
Order {id} was already cancelled	Stornierung	200	Order bereits storniert
MMP triggered during fill processing	MMP	200	MMP-Konfiguration prüfen, Limits anpassen
Order canceled by MMP trigger	MMP	200	MMP-Konfiguration prüfen, Limits anpassen
signature_verification_failed	Auth	400	Signatur und String-Kodierung prüfen
unauthorized	Auth	401	Agent genehmigen oder mit der Wallet signieren
Price validation failed: ...	Validierung	400	Preis auf ≤ 5 signifikante Stellen runden

Debugging von Ablehnungen

1. Order-Details prüfen: Überprüfen Sie, ob symbol, price, size, side korrekt sind
2. Portfolio prüfen: GET /portfolio?wallet=..., um aktuelle Positionen und Cash einzusehen
3. Tier prüfen: GET /user-tier?wallet=..., um Tier-Beschränkungen zu überprüfen
4. MMP prüfen: GET /mmp-config?wallet=...&currency=..., um MMP-Limits zu überprüfen
5. Markt prüfen: GET /markets und GET /instruments, um zu überprüfen, ob das Instrument existiert
6. Logs überprüfen: Server-Logs können zusätzlichen Kontext enthalten (nicht über die API verfügbar)

Referenzen

• Ablehnungslogik: wird in der Trading-Engine durchgesetzt
• Margin-Prüfungen: werden vor der Order-Zulassung angewendet
• Tier-Prüfungen: werden pro Wallet-Tier durchgesetzt
• Handler-Validierung: Standard-Request-Validierung