Debug SafetyFailure responses
- Capture the exact
safety_failurevariant before changing anything. - Classify the failure as identity, request-shape, market-constraint, or account-state related.
- Repair the specific root cause rather than blindly rebuilding and resubmitting.
- Re-sign and re-encrypt the request when the payload changes.
- Recheck the resulting order, strategy, or trader state after the corrected request succeeds.
Classify the failure first
| Failure family | Typical variants | First thing to inspect |
|---|---|---|
| identity or request-auth defect | SignatureRecoveryMismatch | signing inputs, trader identity, session material |
| product or order-shape defect | UnsupportedMarket, PriceNotMultipleOfTickSize, OrderAmountNotMultipleOfMinOrderSize, OrderTypeIncompatibleWithPrice | symbol, price, amount, order-type fields |
| risk and margin defect | NotEnoughCollateral, OMFLessThanIMF, MaxOrderNotionalBreached, MaxTakerPriceDeviationBreached | collateral, leverage, notional size, mark-price context |
| account or strategy-state defect | TraderNotFound, NoStrategies, StrategyNotFound, TooManyOrders, OrderNotFound | current trader, strategy, and open-order state |
Repair by class
- For signing failures, re-read Request Signing Reference and verify the trader, domain, nonce, timestamp, and optional session payload.
- For encryption-adjacent request handling, re-read Request Encryption Reference and rebuild the encrypted payload after the underlying request is fixed.
- For market-shape failures, re-read Product and Trading Specifications and Trading Safeties and Guards.
- For margin and solvency failures, re-read Margin Requirements and Price Feeds and Mark Price Inputs.
- For order-state failures, inspect the current order and account events before deciding whether the request is stale, duplicate, or aimed at the wrong strategy.
Do not conflate these with other error classes
SafetyFailuremeans the request was understood but rejected by validation or risk guards- replay-window and timestamp failures belong to the broader error system, not the
safety_failureenum - service, rate-limit, and encryption failures have different recovery posture even if they appear during the same workflow
After you fix the root cause
- Rebuild the request payload.
- Re-sign it.
- Re-encrypt it when the submission path requires encrypted transport.
- Submit once and inspect the resulting event trail before deciding whether more repair is needed.
Boundary rule
This page is for structured SafetyFailure triage only. Use the broader error guides when the response class is notSafetyFailure.