Skip to main content
This page describes how TickDB reports errors across REST and WebSocket APIs. It explains the error formats, common status codes, and how to handle them correctly. For endpoint-specific error details, see Error Codes by Endpoint.

​
REST API Error Format

REST API errors are returned with an HTTP status code and a JSON body.

​
Example: Authentication Error (401)

{
  "success": false,
  "error": "Invalid or inactive API key",
  "code": 401
}

​
Example: Rate Limit Error (429)

Rate limit responses may include additional fields to help clients recover or upgrade. 
{
  "success": false,
  "error": "Rate limit exceeded",
  "code": 429,
  "limit": 60,
  "used": 60,
  "reset_at": 1700000000,
  "plan": "free",
  "upgrade_to": "standard"
}

​
WebSocket Error Format

WebSocket errors fall into two categories:
  1. Connection-level errors (HTTP status codes like 401, 403, 429)
  2. Message-level errors with custom error codes

​
Example: Message-level Error

{
  "cmd": "subscribe",
  "code": 2001,
  "message": "symbols parameter is required"
}

​
Common HTTP Status Codes

HTTP StatusDescriptionTypical Cause
200OKRequest succeeded
400Bad RequestMissing or invalid parameters
401UnauthorizedMissing, invalid, or inactive API key
403ForbiddenPermission denied for this endpoint or market
404Not FoundEndpoint or symbol not found
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected server error
502Bad GatewayUpstream service error
503Service UnavailableTemporary service outage

​
Common WebSocket Error Codes

WebSocket error codes are custom codes, not HTTP statuses.
CodeDescriptionTypical Cause
2001Invalid message format or commandMalformed JSON, unknown command, or missing fields
2003Depth subscription unavailableDepth channel temporarily disabled
2004Trade subscription unavailableTrade channel temporarily disabled

​
Error Handling Best Practices

  • Always check the HTTP status code before parsing the response.
  • For 429 errors, wait until reset_at before retrying.
  • Do not retry immediately on 500 errors; use exponential backoff.
  • Validate request parameters locally to avoid 400 errors.
  • For WebSocket APIs:
    • Ensure messages are valid JSON
    • Always include required fields (cmd, channel, symbols)
  • Authentication – API key usage and permissions
  • Data Specification – symbol formats and market definitions
  • Error Codes by Endpoint – detailed error messages per API endpoint