Error Model

Senticore uses a stable error envelope across all JSON surfaces.

HTTP error envelope

{
  "error": {
    "code": "insufficient_collateral",
    "message": "Available collateral below order requirement",
    "retryable": false,
    "details": {
      "required": "1500.00",
      "available": "1200.00"
    }
  }
}

HTTP status mapping

Status	Meaning
200	Success
400	Request validation failed
401	Authentication required or invalid signature
403	Authenticated but not authorized
409	Idempotency conflict or state conflict
422	Business rule rejection
429	Rate limit exceeded
500	Internal error, retryable
503	Service unavailable, retryable

Common error codes

Code	Surface	Retryable	Meaning
unknown_market	All	No	Market id not recognized
tick_size_violation	Trading	No	Price not aligned to market tick
lot_size_violation	Trading	No	Quantity not aligned to lot size
min_notional_violation	Trading	No	Order value below minimum
max_quantity_violation	Trading	No	Per-order cap exceeded
book_depth_full	Trading	No	Price-level cap reached
insufficient_collateral	Trading	No	Pre-trade margin failure
reduce_only_violation	Trading	No	Would increase position
post_only_would_cross	Trading	No	Post-only order would cross the spread
self_trade_prevention	Trading	No	STP rule triggered
nonce_used	Trading	No	Replay protection
nonce_stale	Trading	No	Too old
invalid_signature	All	No	Signature verification failed
wrong_chain_id	All	No	EIP-712 domain mismatch
rate_limited	All	Yes	Backoff per Retry-After
temporary_unavailable	All	Yes	Internal retryable condition

Retry semantics

Clients should:

• retry only retryable: true errors,
• use exponential backoff with jitter starting at 250 ms and capping at 5 seconds,
• respect Retry-After for 429 and 503,
• use idempotency keys so retries are safe,
• surface non-retryable errors to the user or strategy without automatic retry.