Error Codes

All API endpoints return structured error responses with numeric error codes for programmatic handling.

Error Response Format

{
  "code": 2000,
  "message": "Market 0x123... not found"
}

Both REST API and WebSocket responses use the same error format, making it easy to handle errors consistently across your application.

Error Code Ranges

Range	Category	Description
1xxx	General	Internal errors, invalid requests, rate limiting
2xxx	Market	Market not found, paused, or already exists
3xxx	Order	Order not found, not active, invalid params
4xxx	Account/Session	Authentication, session, whitelist errors
5xxx	Trade	Trade not found, invalid trade count
6xxx	Subscription	WebSocket subscription errors
7xxx	Validation	Amount, time range, pagination errors
8xxx	Block/Events	Block or events not found

Complete Error Code Reference

General Errors (1xxx)

Code	Name	Description
1000	InternalError	Unexpected server error
1001	InvalidRequest	Malformed or invalid request
1002	ParseError	Failed to parse request body
1003	RateLimitExceeded	Too many requests
1004	GeoRestricted	Region not allowed

Market Errors (2xxx)

Code	Name	Description
2000	MarketNotFound	Specified market does not exist
2001	MarketPaused	Market is currently paused
2002	MarketAlreadyExists	Market already exists

Order Errors (3xxx)

Code	Name	Description
3000	OrderNotFound	Specified order does not exist
3001	OrderNotActive	Order is not in active state
3002	InvalidOrderParams	Invalid order parameters

Account/Session Errors (4xxx)

Code	Name	Description
4000	InvalidSignature	Signature verification failed
4001	InvalidSession	Session is invalid
4002	AccountNotFound	Trading account not found
4003	WhitelistNotConfigured	Whitelist not configured

Trade Errors (5xxx)

Code	Name	Description
5000	TradeNotFound	Specified trade does not exist
5001	InvalidTradeCount	Invalid trade count requested

Subscription/WebSocket Errors (6xxx)

Code	Name	Description
6000	AlreadySubscribed	Already subscribed to topic
6001	TooManySubscriptions	Subscription limit exceeded
6002	SubscriptionError	WebSocket subscription error

Validation Errors (7xxx)

Code	Name	Description
7000	InvalidAmount	Invalid amount specified
7001	InvalidTimeRange	Invalid time range
7002	InvalidPagination	Invalid pagination parameters
7003	NoActionsProvided	No actions in request
7004	TooManyActions	Too many actions in request

Block/Events Errors (8xxx)

Code	Name	Description
8000	BlockNotFound	Block not found
8001	EventsNotFound	Events not found for block

Handling Errors

Example: JavaScript/TypeScript

const response = await fetch('https://api.o2.xyz/v1/markets/invalid-id');
const data = await response.json();

if (data.code) {
  switch (data.code) {
    case 2000:
      console.error('Market not found:', data.message);
      break;
    case 1003:
      console.error('Rate limited, retry later');
      break;
    default:
      console.error(`Error ${data.code}: ${data.message}`);
  }
}

Example: Rust

#[derive(Deserialize)]
struct ApiError {
    code: u32,
    message: String,
}

match error.code {
    2000 => println!("Market not found: {}", error.message),
    1003 => println!("Rate limited, retry later"),
    _ => println!("Error {}: {}", error.code, error.message),
}

WebSocket Error Handling

WebSocket connections receive errors in the same format:

{
  "code": 6001,
  "message": "Subscription limit exceeded"
}

Common WebSocket error scenarios:

• 6000 (AlreadySubscribed) - Attempting to subscribe to a topic you're already subscribed to
• 6001 (TooManySubscriptions) - Exceeded the maximum number of subscriptions per connection
• 6002 (SubscriptionError) - General subscription error (e.g., invalid market ID)