Error Codes
All errors return JSON with error (string) and code (integer).
HTTP Status Codes
| Code | Meaning | When |
|---|---|---|
| 200 | OK | Successful request |
| 400 | Bad Request | Invalid parameters (wrong enum value, invalid combination) |
| 401 | Unauthorized | Missing/invalid Authorization: Bearer <key> header |
| 500 | Internal Server Error | Database query failure or unexpected server error |
| 503 | Service Unavailable | One or more backends down (only from /ready) |
Error Response Format
{"error": "Human-readable description", "code": 400}Specific 400 Errors
| Endpoint | Trigger | Error Message |
|---|---|---|
| /v1/wallets/:addr/performance | Invalid window | "Invalid window. Use 1d, 7d, or 30d" |
| /v1/wallets/:addr/positions | Invalid status | "Invalid status. Use open, closed, or all" |
| /v1/leaderboard | Invalid window | "Invalid window. Use 1d, 7d, or 30d" |
| /v1/leaderboard | Invalid sort | "Invalid sort. Use pnl_usd, roi, or win_rate" |
| /v1/tokens/:mint/ohlcv | Invalid timeframe/view | "Invalid timeframe/view combination. Use timeframe=1s|1m|5m|15m|1h and view=full|filtered" |
WebSocket Errors
Sent as {"op": "error", "message": "..."}. Do not close the connection.
| Trigger | Message |
|---|---|
| Malformed JSON | "Invalid message format" |
| Too many subscriptions | "Subscription limit reached (max 50)" |
| Invalid channel name | "Invalid channel '...'. Expected: token:<mint>:trades|ticks|ohlcv:<view>:<tf> or wallet:<address>:pnl|positions" |
| Invalid OHLCV view | "Invalid OHLCV view '...'. Use 'full' or 'filtered'" |
| Invalid OHLCV timeframe | "Invalid OHLCV timeframe '...'. Use 1s, 1m, 5m, 15m, or 1h" |
| Empty key | "Empty key in channel" |
| Invalid key chars | "Invalid characters in key '...'" |
| Key too long | "Key too long (max 64 chars)" |