Error Handling | Paradex

The Paradex WebSocket API uses JSON-RPC 2.0 for communication, which includes standardized error handling. This page explains the error format and common error codes.

Error Message Format

When an error occurs, the WebSocket API returns an error message with the following format:

{
  "jsonrpc": "2.0",
  "error": { 
    "code": -32601, 
    "message": "method does not exist" 
  },
  "usIn": 1710522972729581,
  "usOut": 1710522972729618,
  "usDiff": 37,
  "id": 4
}

Error Object Properties

Property	Type	Description	Required
code	number	Error code	Yes
message	string	Short explanation	Yes
data	string	Extra details	No

Error Codes

The Paradex WebSocket API uses standard JSON-RPC error codes as well as custom error codes.

Standard JSON-RPC Error Codes

Error codes from -32768 to -32000 are pre-defined errors per the JSON-RPC specification:

Code	Description
-32700	Parse error
-32600	Invalid request
-32601	Method not found
-32602	Invalid parameters
-32603	Internal error

Paradex-Specific Error Codes

Other errors are specific to the Paradex WebSocket API:

Code	Message	Description
40110	malformed bearer token	The JWT passed to `auth` could not be parsed
40111	invalid bearer token	The JWT passed to `auth` is expired or not valid
40112	service access restricted in your region	Access is blocked for the region of the connecting IP
40300	permission denied	The session is not allowed to perform the request, for example an order method before `auth`, an order on an account the token does not cover, or a private channel without authentication. `data` gives the reason
40301	SBE binary encoding required	The public channel requires SBE encoding. `data` gives the URL parameters to reconnect with. See Binary Encoding (SBE)
42900	max subscriptions per connection reached	The connection already holds the maximum number of subscriptions. See Rate Limits
42901	message rate limit exceeded	The account exceeded its order rate limit on an `order.*` method. Retry after backing off. See Rate Limits

Close Codes

The server may close a connection with one of the following Paradex close codes. The close reason is a JSON object with a reason field.

Code	Reason	Description
4031	no active subscriptions	The connection held no subscriptions for 5 minutes. Keep at least one subscription open, for example `orders.ALL`, on connections used only for order entry
4032	inbound queue full	The client sent messages faster than the server could process them, for example several hundred requests in one burst. Slow down before reconnecting

The server may also close a connection with the standard close code 1001 (going away), for example during a deployment. Reconnect when this happens.

Common Error Scenarios

Authentication Errors

Authentication errors occur when there are issues with the JWT token:

{
  "jsonrpc": "2.0",
  "error": { 
    "code": 40111, 
    "message": "invalid bearer token" 
  },
  "usIn": 1710522972729581,
  "usOut": 1710522972729618,
  "usDiff": 37,
  "id": 0
}

Subscription Errors

Subscription errors occur when there are issues with channel subscriptions:

{
  "jsonrpc": "2.0",
  "error": { 
    "code": -32602, 
    "message": "invalid method parameters" 
  },
  "usIn": 1710522972729581,
  "usOut": 1710522972729618,
  "usDiff": 37,
  "id": 1
}

Method Errors

Method errors occur when an invalid method is called:

{
  "jsonrpc": "2.0",
  "error": { 
    "code": -32601, 
    "message": "method does not exist" 
  },
  "usIn": 1710522972729581,
  "usOut": 1710522972729618,
  "usDiff": 37,
  "id": 4
}

Best Practices for Error Handling

Check Error Codes: Always check the error code to understand the type of error
Log Errors: Log all errors for debugging purposes
Implement Retry Logic: For transient errors, implement retry logic with exponential backoff
Handle Authentication Errors: If you receive an authentication error, regenerate your JWT token and reconnect
Validate Parameters: Ensure all parameters are valid before sending requests