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 |
| 403 | Forbidden | API key’s tier does not grant access to this endpoint |
| 404 | Not Found | Resource does not exist |
| 429 | Too Many Requests | Per-tier rate limit exceeded |
| 500 | Internal Server Error | Database query failure or unexpected server error |
| 503 | Service Unavailable | Authentication or another required backend is temporarily unavailable; /ready also uses 503 while dependencies are down |
Successful identity no-match states
Not every absence is a 404. These Layer 2 identity requests return HTTP 200 when the input is syntactically accepted but no active association exists:
| Endpoint | Stable no-match body |
|---|---|
/v1/wallet/:addr/identity | {"wallet_address":"...","primary":null,"aliases":[]} |
/v1/kol-wallets/:username | {"username":"normalized","wallets":[]} |
Keep these distinct from a 400 invalid input and from a 500/503 dependency failure. Do not reinterpret either successful empty body as proof that a wallet is anonymous, safe, or not publicly associated outside the current registry.
Error Response Format
{"error": "Human-readable description", "code": 400}Specific 400 Errors
| Endpoint | Trigger | Error Message |
|---|---|---|
| /v1/wallet/:addr/performance | Invalid window | "Invalid window. Use 1d, 7d, or 30d" |
| /v1/wallet/:addr/positions | Invalid status | "Invalid status. Use open, closed, or all" |
| /v1/kol-wallets/:username | Invalid username grammar | "Invalid username" |
| /v1/kol-wallets/:username | Invalid platform | "Invalid platform. Use x or telegram" |
| /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/token/: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>|security|campaign|bundles|dump_alert or wallet:<address>:pnl|positions|labels|security|follow|entity" |
| 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)" |