Errors

Error response format, error codes, and HTTP status codes for REST and WebSocket APIs.

All errors follow a consistent format with a code, message, and optional details.

Error Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {
      "field": "additional context"
    }
  }
}

Error Codes

Authentication Errors

Code	HTTP	Description
`INVALID_API_KEY`	401	Missing or invalid API key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing or invalid API key"
  }
}

Validation Errors

Code	HTTP	Description
`INVALID_PARAMS`	400	General parameter validation failure
`INVALID_EXCHANGE`	400	Unknown/unsupported exchange ID, duplicate exchange in aggregate string, or non-alphabetical aggregate ordering
`INVALID_SYMBOL`	400	Unknown or unsupported trading symbol
`INVALID_TIMEFRAME`	400	Invalid timeframe format or outside allowed range
`INVALID_BUCKET`	400	Invalid or restricted bucket group
`INVALID_STREAM`	400	Invalid or unknown stream type

{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid request parameters",
    "details": {
      "message": "from and to are required"
    }
  }
}

{
  "error": {
    "code": "INVALID_TIMEFRAME",
    "message": "Invalid timeframe format",
    "details": {
      "timeframe": "2x"
    }
  }
}

{
  "error": {
    "code": "INVALID_EXCHANGE",
    "message": "Invalid exchange",
    "details": {
      "exchange": "unknown",
      "valid_exchanges": ["binancef", "bybitf", "coinbase", "okx", "deribit", "hyperliquid"]
    }
  }
}

For invalid aggregated exchange strings, REST responses use the same INVALID_EXCHANGE code and include details such as:

{
  "error": {
    "code": "INVALID_EXCHANGE",
    "message": "Invalid exchange",
    "details": {
      "message": "invalid aggregated exchange string: exchanges must be ordered alphabetically",
      "provided": "bybitf:binancef",
      "expected": "binancef:bybitf"
    }
  }
}

Tier Restriction Errors

Code	HTTP	Description
`TIER_RESTRICTED`	403	Request outside tier's allowed access
`AGG_NOT_ALLOWED`	403	Multi-exchange aggregation not allowed on tier
`MAX_POINTS_EXCEEDED`	400	Request exceeds maximum datapoints

{
  "error": {
    "code": "TIER_RESTRICTED",
    "message": "Data outside tier's allowed range",
    "details": {
      "max_history_days": 90,
      "earliest_allowed": 1701475200
    }
  }
}

max_history_days is plan-dependent (for example: Basic Monthly 90, Basic Yearly 365, Pro Yearly 0 for unlimited).

{
  "error": {
    "code": "AGG_NOT_ALLOWED",
    "message": "Aggregated requests not allowed on your plan"
  }
}

{
  "error": {
    "code": "MAX_POINTS_EXCEEDED",
    "message": "Request exceeds max datapoints for stream",
    "details": {
      "requested": 150000,
      "max": 100000
    }
  }
}

Rate Limit Errors

Code	HTTP	Description
`RATE_LIMITED`	429	Rate limit exceeded

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "details": {
      "retry_after": 45
    }
  }
}

WebSocket Errors

Code	HTTP	Description
`MAX_SUBS_EXCEEDED`	400	Maximum subscriptions exceeded on connection
`MAX_CONNS_EXCEEDED`	429	Too many WebSocket connections
`INVALID_MESSAGE`	400	Malformed WebSocket message
`UNKNOWN_CHANNEL`	400	Unknown subscription channel
`ALREADY_SUBSCRIBED`	400	Already subscribed to this stream
`NOT_SUBSCRIBED`	400	Not subscribed to this stream

{
  "error": {
    "code": "MAX_SUBS_EXCEEDED",
    "message": "Maximum subscriptions exceeded",
    "details": {
      "max": 100,
      "current": 100
    }
  }
}

Bucket Validation Errors

When an invalid or restricted bucket group is requested:

{
  "error": {
    "code": "INVALID_BUCKET",
    "message": "Invalid or restricted bucket group",
    "details": {
      "bucket": "15",
      "valid_buckets": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
      "bucket_descriptions": {
        "1": "all",
        "2": "1-1K",
        "3": "1K-10K",
        "4": "10K-25K",
        "5": "25K-50K",
        "6": "50K-100K",
        "7": "100K-250K",
        "8": "250K-500K",
        "9": "500K-1M",
        "10": "1M-5M",
        "11": "5M+"
      }
    }
  }
}

Server Errors

Code	HTTP	Description
`TIMEOUT`	504	Query exceeded 30 second timeout
`INTERNAL_ERROR`	500	Internal server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable

{
  "error": {
    "code": "TIMEOUT",
    "message": "Query exceeded 30s timeout",
    "details": {
      "request_id": "01HQXYZ123ABC456DEF789GHI"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error",
    "details": {
      "request_id": "01HQXYZ123ABC456DEF789GHI"
    }
  }
}

WebSocket Error Messages

WebSocket errors are sent as JSON messages on the connection:

{
  "type": "error",
  "code": "INVALID_MESSAGE",
  "message": "Failed to parse message"
}

WebSocket Error Codes

Code	Description
`INVALID_JSON`	Message is not valid JSON
`UNKNOWN_TYPE`	Unknown message type
`INVALID_MESSAGE`	Malformed WebSocket message
`INVALID_PARAMS`	Missing required fields
`INVALID_STREAM`	Unknown or invalid channel
`INVALID_EXCHANGE`	Unknown exchange ID, duplicate exchange in aggregate string, or non-alphabetical aggregate ordering
`INVALID_TIMEFRAME`	Invalid timeframe format or outside allowed range
`INVALID_BUCKET`	Invalid or restricted bucket group
`MAX_SUBS_EXCEEDED`	Maximum subscriptions reached
`ALREADY_SUBSCRIBED`	Already subscribed to this stream
`NOT_SUBSCRIBED`	Not subscribed to this stream

After certain errors (like MAX_CONNS_EXCEEDED), the server will close the connection.

HTTP Status Code Summary

Status	Meaning
200	Success
400	Bad request (validation error)
401	Unauthorized (invalid API key)
403	Forbidden (tier restriction)
429	Too many requests (rate limited)
500	Internal server error
503	Service unavailable
504	Gateway timeout

Errors

On this page