Every developer has encountered it: your application runs perfectly in testing, then collapses in production because a third-party API returned an opaque error, and you had no idea whether to retry, wait, or give up entirely.
The scene is familiar. You check the logs. You see 429. You think: rate limit. But is it? The HTTP 429 status code means "Too Many Requests," but the response body contains something entirely different—perhaps a vendor-specific error code, a cryptic message, or nothing useful at all. You write a retry loop with exponential backoff. You wait. The error persists. Eventually, you discover the 429 wasn't a rate limit at all. It was a quota exceeded notification that requires a different remediation path entirely.
This is the problem TickDB set out to solve with its unified error code system. The choice to use 3001 instead of returning a raw HTTP 429 is not an accident. It is a deliberate architectural decision with significant implications for developer experience, reliable integration design, and long-term API stability.
The Problem with HTTP Status Codes for API Error Handling
HTTP status codes were designed for a different era. The original HTTP/1.1 specification defined 41 status codes, optimized for hypertext navigation. When a browser requests a page that doesn't exist, the server responds with 404. When authentication fails, 401. When rate limiting applies, 429.
These codes work reasonably well for web servers. They are a thin layer of machine-readable metadata sitting on top of human-readable HTML responses. A web browser doesn't need to know why a page is unavailable—it just needs a status code that tells it whether to show an error page or redirect.
API integrations are fundamentally different. An API client receives a response and must decide what to do next: parse the data, retry the request, escalate to a human, or halt operation entirely. That decision requires precise, structured information about what went wrong.
HTTP 429 is insufficient for this purpose. It tells you that you sent too many requests, but it doesn't tell you:
- Whether you exceeded a per-second rate limit or a daily quota
- How long to wait before retrying
- Whether other endpoints are affected or just this one
- What action you must take to resolve the issue (upgrade plan, contact support, wait)
To compensate for these gaps, API developers have historically added proprietary error structures on top of HTTP status codes. The response body might contain a JSON object with error_code, message, retry_after, and other fields. This approach works, but it creates fragmentation. Every API has a different error body schema. Every SDK must implement custom parsing logic. Every developer must read unique documentation to understand what each error means.
The result is a landscape of inconsistent error handling, where developers spend more time debugging error responses than building features.
TickDB's Error Code Philosophy
TickDB adopted a unified error code system that replaces the ambiguity of HTTP status codes with a structured, internally consistent numbering scheme. Every error returned by the TickDB API—regardless of which endpoint you call or which programming language you use—shares the same error code taxonomy.
The system has three primary tiers:
1xxx codes: Authentication and authorization errors
1001: Invalid API key1002: Missing API key
2xxx codes: Resource and data errors
2001: Parameter validation error2002: Symbol not found
3xxx codes: Rate limiting and system errors
3001: Rate limit exceeded3002: Internal server error
This tiered structure is not arbitrary. The hundreds digit encodes the error category, making it immediately identifiable in logs and monitoring systems. A monitoring dashboard can alert on any 3xxx error without knowing the specific code, because all 3xxx codes share a common property: they represent transient or system-level conditions that may resolve on retry.
Why 3001 Instead of 429?
The choice of 3001 over HTTP 429 reflects a fundamental difference in how TickDB models its error responses.
HTTP 429 is a transport-layer signal. It tells you that your request was rejected at the HTTP layer because of traffic management. It provides minimal semantic information.
TickDB 3001 is an application-layer error code. It tells you that your request was rejected because you exceeded a rate limit enforced by the TickDB platform. The error body provides additional context: which limit was hit, when it resets, and what action to take.
More importantly, the 3001 code is consistent regardless of the underlying HTTP response code that the client receives. In some configurations, a rate-limited request might return 429 with a 3001 error code in the body. In others, it might return 200 with an error body (for WebSocket upgrades or streaming responses, where HTTP error codes disrupt the protocol). By decoupling the application error from the HTTP status code, TickDB ensures that clients using any HTTP version, any transport configuration, or any proxy layer receive the same semantic error.
The Retry-After Standard
Rate limiting errors require a specific handling protocol. When a client receives 3001, the response includes a Retry-After header indicating the number of seconds to wait before retrying.
Here is the standard error response structure for a rate limit error:
{
"code": 3001,
"message": "Rate limit exceeded. Please retry after the specified time.",
"retry_after": 5
}
The accompanying HTTP headers might look like this:
HTTP/1.1 429 Too Many Requests
Retry-After: 5
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712345678
The retry_after field in the body and the Retry-After header are synchronized. Clients should read the body field for programmatic access and the header for HTTP-semantic tools (caches, proxies, CDN configurations).
The 5 second window is not chosen arbitrarily. It represents the minimum safe interval for the standard rate limit tier. Heavy users may encounter longer windows, and the value adjusts dynamically based on platform load. The correct approach is to always read the actual value rather than hardcoding assumptions.
Production-Grade Error Handling Code
Proper error handling in production code requires more than a simple try-catch block. The following Python implementation demonstrates the complete error handling workflow for TickDB API integration, including rate limit handling with exponential backoff and jitter.
import os
import time
import random
import logging
from typing import Optional, Dict, Any
from urllib.parse import urlencode
import requests
logger = logging.getLogger(__name__)
# Load API key from environment variable
# ⚠️ Never hardcode API keys in production code
TICKDB_API_KEY = os.environ.get("TICKDB_API_KEY")
if not TICKDB_API_KEY:
raise EnvironmentError("TICKDB_API_KEY environment variable is not set")
BASE_URL = "https://api.tickdb.ai/v1"
class TickDBError(Exception):
"""Base exception for all TickDB errors."""
def __init__(self, code: int, message: str, retry_after: Optional[int] = None):
self.code = code
self.message = message
self.retry_after = retry_after
super().__init__(f"[{self.code}] {self.message}")
class RateLimitError(TickDBError):
"""Raised when rate limit (code 3001) is encountered."""
def __init__(self, message: str, retry_after: int):
super().__init__(code=3001, message=message, retry_after=retry_after)
class AuthenticationError(TickDBError):
"""Raised for auth failures (1001, 1002)."""
pass
class ResourceNotFoundError(TickDBError):
"""Raised when a symbol or resource is not found."""
pass
def parse_error_response(response: requests.Response) -> Dict[str, Any]:
"""Parse TickDB error response from HTTP response.
Handles both successful HTTP codes with error bodies and HTTP error codes.
"""
try:
body = response.json()
except ValueError:
# Non-JSON response; use HTTP status as fallback
return {"code": response.status_code, "message": response.text}
return body
def handle_tickdb_error(response: requests.Response, symbol: Optional[str] = None) -> Any:
"""Convert TickDB error response to appropriate exception.
Args:
response: The HTTP response object
symbol: Optional symbol name for error context
Returns:
Raises the appropriate TickDBError subclass
"""
body = parse_error_response(response)
code = body.get("code", 0)
message = body.get("message", "Unknown error")
if code == 0:
# No error; return data
return body.get("data")
if code in (1001, 1002):
raise AuthenticationError(
message,
retry_after=None
)
if code == 2002:
raise ResourceNotFoundError(
f"Symbol {symbol or 'unknown'} not found. Verify symbol via /v1/symbols/available",
retry_after=None
)
if code == 3001:
# Rate limit exceeded — extract retry_after from body or headers
retry_after = body.get("retry_after")
if retry_after is None:
retry_after = int(response.headers.get("Retry-After", 5))
raise RateLimitError(message, retry_after=retry_after)
# Catch-all for unexpected error codes
raise TickDBError(
code=code,
message=message,
retry_after=None
)
def fetch_with_retry(
endpoint: str,
params: Optional[Dict[str, Any]] = None,
max_retries: int = 5,
base_delay: float = 1.0,
max_delay: float = 60.0
) -> Any:
"""Fetch data from TickDB API with exponential backoff and jitter.
Args:
endpoint: API endpoint path (e.g., "/market/kline")
params: Query parameters dictionary
max_retries: Maximum number of retry attempts
base_delay: Initial delay in seconds
max_delay: Maximum delay cap in seconds
Returns:
Parsed API response data
Raises:
AuthenticationError: If API key is invalid
ResourceNotFoundError: If symbol not found
RateLimitError: If rate limit persists after max_retries
TickDBError: For other API errors
"""
headers = {"X-API-Key": TICKDB_API_KEY}
url = f"{BASE_URL}{endpoint}"
for attempt in range(max_retries):
try:
response = requests.get(
url,
headers=headers,
params=params,
timeout=(3.05, 10) # Connect timeout, read timeout
)
if response.ok and response.status_code != 429:
# Success or non-rate-limit HTTP error with no body
body = parse_error_response(response)
if body.get("code", 0) == 0:
return body.get("data")
# Handle error condition
error = handle_tickdb_error(response, symbol=params.get("symbol") if params else None)
if isinstance(error, RateLimitError):
# Exponential backoff with jitter
delay = min(base_delay * (2 ** attempt), max_delay)
# Add jitter: random value between 0 and 10% of delay
jitter = random.uniform(0, delay * 0.1)
sleep_time = delay + jitter
logger.warning(
f"Rate limit hit (attempt {attempt + 1}/{max_retries}). "
f"Retrying in {sleep_time:.2f}s. Error: {error.message}"
)
time.sleep(sleep_time)
continue
# Non-retryable error
raise error
except requests.exceptions.Timeout:
logger.warning(f"Request timeout (attempt {attempt + 1}/{max_retries})")
if attempt == max_retries - 1:
raise
continue
except requests.exceptions.ConnectionError as e:
logger.warning(f"Connection error (attempt {attempt + 1}/{max_retries}): {e}")
if attempt == max_retries - 1:
raise
continue
# Exhausted retries
raise RateLimitError(
"Rate limit exceeded after maximum retries",
retry_after=max_delay
)
def fetch_kline_data(symbol: str, interval: str = "1h", limit: int = 100) -> Any:
"""Fetch historical OHLCV kline data for a symbol.
Args:
symbol: Trading symbol (e.g., "BTC.USDT")
interval: Kline interval (e.g., "1m", "1h", "1d")
limit: Number of candles to fetch (max 1000)
Returns:
List of kline records
Raises:
ResourceNotFoundError: If symbol not found
RateLimitError: If rate limit exceeded
"""
params = {
"symbol": symbol,
"interval": interval,
"limit": min(limit, 1000)
}
return fetch_with_retry("/market/kline", params=params)
def fetch_available_symbols(category: Optional[str] = None) -> Any:
"""Fetch list of available symbols.
Args:
category: Optional filter (e.g., "US", "HK", "crypto")
Returns:
List of available symbols
"""
params = {}
if category:
params["category"] = category
return fetch_with_retry("/symbols/available", params=params)
WebSocket Error Handling
WebSocket connections require a different error handling approach, since the protocol does not use HTTP status codes in the same way. The following TypeScript implementation demonstrates proper WebSocket error handling with reconnection logic:
interface TickDBWebSocketMessage {
code: number;
message?: string;
retry_after?: number;
[key: string]: unknown;
}
class TickDBWebSocketClient {
private ws: WebSocket | null = null;
private apiKey: string;
private reconnectAttempts = 0;
private maxReconnectAttempts = 10;
private baseReconnectDelay = 1000;
private maxReconnectDelay = 30000;
private heartbeatInterval: ReturnType<typeof setInterval> | null = null;
constructor(apiKey: string) {
if (!apiKey) {
throw new Error("TickDB API key is required");
}
this.apiKey = apiKey;
}
private calculateReconnectDelay(): number {
// Exponential backoff with jitter
const exponentialDelay = Math.min(
this.baseReconnectDelay * Math.pow(2, this.reconnectAttempts),
this.maxReconnectDelay
);
// Add jitter: 0-10% of delay
const jitter = Math.random() * exponentialDelay * 0.1;
return exponentialDelay + jitter;
}
private handleError(message: TickDBWebSocketMessage): void {
const { code, message: errorMessage, retry_after } = message;
switch (code) {
case 3001:
// Rate limit exceeded
const waitTime = retry_after ?? 5;
console.warn(`Rate limit hit. Waiting ${waitTime}s before reconnecting.`);
setTimeout(() => this.connect(), waitTime * 1000);
break;
case 1001:
case 1002:
// Authentication error — do not retry automatically
console.error(`Authentication failed (code ${code}): ${errorMessage}`);
this.cleanup();
throw new Error(`TickDB authentication failed. Check your API key.`);
default:
console.error(`TickDB error ${code}: ${errorMessage}`);
// Retry with backoff for unknown errors
this.scheduleReconnect();
}
}
private scheduleReconnect(): void {
if (this.reconnectAttempts >= this.maxReconnectAttempts) {
console.error("Max reconnection attempts reached. Giving up.");
this.cleanup();
return;
}
const delay = this.calculateReconnectDelay();
this.reconnectAttempts++;
console.log(`Reconnecting in ${Math.round(delay)}ms (attempt ${this.reconnectAttempts})`);
setTimeout(() => this.connect(), delay);
}
private startHeartbeat(): void {
this.heartbeatInterval = setInterval(() => {
if (this.ws?.readyState === WebSocket.OPEN) {
this.ws.send(JSON.stringify({ cmd: "ping" }));
}
}, 30000);
}
private cleanup(): void {
if (this.heartbeatInterval) {
clearInterval(this.heartbeatInterval);
this.heartbeatInterval = null;
}
if (this.ws) {
this.ws.close();
this.ws = null;
}
this.reconnectAttempts = 0;
}
connect(): void {
// API key passed as URL parameter for WebSocket authentication
const wsUrl = `wss://ws.tickdb.ai/v1?api_key=${this.apiKey}`;
this.ws = new WebSocket(wsUrl);
this.ws.onopen = () => {
console.log("TickDB WebSocket connected");
this.reconnectAttempts = 0;
this.startHeartbeat();
};
this.ws.onmessage = (event) => {
try {
const message = JSON.parse(event.data) as TickDBWebSocketMessage;
if (message.code && message.code !== 0) {
this.handleError(message);
return;
}
// Process normal message
this.onMessage(message);
} catch (error) {
console.error("Failed to parse WebSocket message:", error);
}
};
this.ws.onerror = (error) => {
console.error("WebSocket error:", error);
};
this.ws.onclose = () => {
console.log("WebSocket connection closed");
this.cleanup();
// Attempt reconnection unless this was a clean close
this.scheduleReconnect();
};
}
// Override this method in subclass or pass as callback
onMessage(message: TickDBWebSocketMessage): void {
console.log("Received message:", message);
}
subscribe(channel: string, params: Record<string, string>): void {
if (this.ws?.readyState === WebSocket.OPEN) {
this.ws.send(JSON.stringify({
cmd: "subscribe",
channel,
...params
}));
} else {
throw new Error("WebSocket not connected");
}
}
disconnect(): void {
this.cleanup();
}
}
Developer Benefits of Unified Error Codes
The unified error code system delivers concrete benefits that compound over time.
Consistent Error Handling Across All Endpoints
A developer who learns that 1001 means "invalid API key" can apply that knowledge everywhere in the TickDB ecosystem. The same is true for 2002 (symbol not found), 3001 (rate limit), and every other code in the system.
This consistency eliminates the need to consult endpoint-specific documentation for every error scenario. Once you understand the taxonomy, you understand the error behavior of the entire API.
Structured Monitoring and Alerting
Monitoring systems can alert on error code ranges rather than specific messages. An alert on "any 3xxx error in the last 5 minutes" captures all rate limiting and system errors without requiring you to enumerate every possible error message variant.
This approach scales gracefully as the API evolves. When TickDB adds new 3xxx error codes for new system conditions, existing monitoring rules automatically capture them without modification.
Reduced Debugging Time
When an integration fails in production, the error code provides immediate context. 1001 tells you exactly what to investigate (API key validity). 3001 tells you exactly what to do (wait and retry). 2002 tells you exactly what to verify (symbol availability).
Compare this to the alternative: a raw HTTP 429 with a generic "rate exceeded" message and no guidance on remediation.
Cross-Language SDK Development
The unified error code system simplifies SDK development across programming languages. Each SDK can map the same error codes to idiomatic exception types—RateLimitError in Python, RateLimitException in Java, RateLimitError in TypeScript—without negotiating custom code schemes for each language.
Comparison: TickDB 3001 vs HTTP 429
The following table summarizes the key differences between the TickDB error code approach and raw HTTP 429:
| Dimension | HTTP 429 | TickDB 3001 |
|---|---|---|
| Layer | Transport (HTTP) | Application (API) |
| Semantic clarity | Ambiguous (could be rate limit, quota, or something else) | Precise (rate limit enforced by TickDB platform) |
| Retry guidance | Via Retry-After header only | Via body field + header + retry_after value |
| Consistency across transport modes | Inconsistent (429 not valid for WebSocket) | Consistent across REST, WebSocket, and streaming |
| Error code taxonomy | Single code for all "too many requests" | System of codes covering auth, resource, and system errors |
| SDK mapping | Requires custom per-endpoint error handling | Standard error code → standard exception type |
The 3001 code exists within a broader system. It is not an isolated design choice but a component of a coherent error handling architecture that provides consistency, structure, and actionable guidance at every level of the API surface.
Best Practices for Developers
Adopting these practices will help you build resilient integrations that handle errors gracefully.
Always read the error body, not just the HTTP status code. HTTP status codes can be misleading. The error body contains the semantic truth about what went wrong.
Implement exponential backoff with jitter. Do not retry immediately after a rate limit error. The retry_after value is a minimum safe interval; adding randomness prevents thundering herd scenarios where many clients retry simultaneously after the same wait period.
Log error codes, not just messages. Error codes are stable identifiers; messages may change between API versions. When debugging, the error code is the reliable anchor.
Separate retryable from non-retryable errors. 3001 is retryable. 1001 and 1002 are not. Your retry logic should distinguish between these categories to avoid spinning on authentication failures.
Monitor rate limit patterns. If your application frequently triggers 3001, it may be operating at the edge of its tier's limits. Consider optimizing request patterns or evaluating plan upgrades before hitting critical failures.
Conclusion
The choice to use 3001 instead of HTTP 429 reflects a fundamental commitment to structured, developer-centric error handling. HTTP status codes were designed for web navigation, not API integration. By defining a unified error code taxonomy, TickDB provides developers with precise, consistent, and actionable error information that works across all endpoints, all transport modes, and all SDK languages.
When your application encounters a 3001 error, you know exactly what happened and exactly what to do. You wait for the retry_after interval, implement the exponential backoff with jitter, and retry. No ambiguity. No guesswork. No wasted debugging hours.
This is what a well-designed error system looks like in practice: not just telling you that something went wrong, but telling you why and how to recover.
Next Steps
If you're integrating TickDB into a production system, implement the error handling patterns shown in this article. Pay particular attention to the exponential backoff with jitter logic, which prevents the thundering herd problem that causes rate-limited systems to collapse under retry storms.
If you're evaluating API providers, the error handling design is a window into their engineering philosophy. A provider that takes error codes seriously—like TickDB's 3001 system—has likely applied the same rigor to every other aspect of their API design.
If you want to test this in practice:
- Sign up at tickdb.ai (free tier available, no credit card required)
- Generate an API key in the dashboard
- Set
TICKDB_API_KEYas an environment variable - Run the code examples from this article
The error handling code patterns shown here are production-ready. Adapt them to your specific application architecture, and you will build integrations that are resilient, maintainable, and easy to debug.
This article does not constitute investment advice. Markets involve risk; past performance does not guarantee future results.