Error Handling

This guide covers error formats, common error types, and implementation patterns for the Synthetix API.

Error Response Format

All API errors follow a consistent JSON format:

{
  "status": "error",
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to list subaccounts",
    "details": { /* optional context */ }
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

Example Error Response

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Insufficient margin for trade",
    "details": {
      "requiredMargin": "1000.00",
      "availableMargin": "500.12"
    }
  },
  "request_id": "a1b2c3d4e5f67890",
  "timestamp": "2025-01-01T00:00:00.500Z"
}

HTTP Status Codes

Status Code	Description	Common Causes
`200`	Success	Request processed successfully
`400`	Bad Request	Invalid request format, missing parameters
`401`	Unauthorized	Invalid signature, authentication failed
`403`	Forbidden	Insufficient permissions, account restricted
`404`	Not Found	Invalid endpoint, resource not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server-side error
`503`	Service Unavailable	System maintenance, temporary outage

Common Error Types

Authentication Errors

Error Message	Description	Solution
`Invalid signature`	EIP-712 signature validation failed	Verify signing implementation, check domain separator
`Signature expired`	Request timestamp too old	Ensure system clock is synchronized
`Invalid nonce`	Nonce already used or invalid	Use incrementing nonce, check nonce management
`Unauthorized subaccount access`	No permission for subaccount trading	Verify delegation permissions for subaccount

Trading Errors

Error Code	Description	Solution
`VALIDATION_ERROR`	Not enough collateral for order	Add more collateral or reduce order size
`NOT_FOUND`	Order ID doesn't exist	Verify order ID, check if already filled/cancelled
`NOT_FOUND`	Invalid market symbol	Check supported markets, verify symbol format
`INVALID_VALUE`	Unsupported order type or parameters	Use supported types: limit, market, trigger
`VALIDATION_ERROR`	Below minimum order size	Check market minimums
`VALIDATION_ERROR`	Exceeds maximum order size	Check position limits, split into smaller orders
`VALIDATION_ERROR`	Maximum position size reached	Reduce position or close existing
`VALIDATION_ERROR`	Post-only order would take liquidity	Adjust price or use different TIF
`VALIDATION_ERROR`	Reduce-only flag with wrong side	Check position side, adjust order

Market Data Errors

Error Message	Description	Solution
`Symbol not found`	Invalid market symbol	Check available markets
`Invalid timeframe`	Unsupported candle timeframe	Use supported timeframes
`Data not available`	Historical data not found	Check date range, data availability

Rate Limit Errors

Error Message	Description	Solution
`Rate limit exceeded`	Too many requests	Implement backoff, reduce request rate
`IP rate limit exceeded`	IP-based limit hit	Distribute requests, use multiple IPs
`Address rate limit exceeded`	Wallet-based limit hit	Optimize request patterns

Validation Errors

Error Message	Description	Solution
`Invalid market symbol`	Symbol format incorrect	Use format: "BTC-USDT"
`Invalid price format`	Price not a valid string	Send prices as strings, not numbers
`Invalid quantity`	Quantity format or value invalid	Send as string, check decimals
`Nonce already used`	Duplicate nonce	Ensure nonce always increases
`Request expired`	expiresAfter timestamp passed	Use longer expiration, check clock sync

Implementation Notes

The Synthetix API provides detailed error information to help identify and resolve issues:

Error codes follow a consistent taxonomy for easy classification
Error details include context-specific information when available
HTTP status codes map to specific error categories
Retry-After headers indicate when to retry rate-limited requests

WebSocket Error Handling

WebSocket connections use a different error format for responses:

{
  "id": "request-123",
  "status": 400,
  "error": {
    "code": 400,
    "message": "Invalid order parameters"
  }
}

WebSocket-specific error codes:

Connection errors result in WebSocket close codes
Authentication failures close the connection with code 1008
Protocol errors use code 1002