WebSocket API
Errors
WebSocket error response format and common integration errors
Error Format
Error messages have a type of error and a human-readable message. There is no numeric code or channel field.
{
"type": "error",
"message": "invalid channel"
}Common Errors
message | Cause | Resolution |
|---|---|---|
empty message | Client sent a zero-length or whitespace-only frame | Send a valid JSON object or text command |
invalid JSON | Frame starts with { but is not valid JSON | Fix the JSON syntax |
no valid commands | Text-format frame could not be parsed into any command | Use the documented text or JSON command format |
unknown operation | op field is not sub, unsub, auth, or ping | Use a supported operation |
invalid channel | Channel name is not recognized | Use a channel from the Channels index |
invalid subscription params | params could not be parsed as subscription parameters | Check the params format for the channel |
authentication required | Subscribed to a private channel before authenticating | Send an auth message first |
missing market | book/ticker subscription has no market param | Include params: { market } |
invalid market | market param is not a known market | Verify the market ID |
missing asset | oracle subscription has no asset param | Include params: { asset } |
invalid asset | asset param is not a known asset | Verify the asset symbol |
only 1 filter allowed | More than one of market/asset/event was sent | Send at most one filter |
filters not allowed | portfolio or notification channel does not accept filters | Remove the params filter from the subscription |
invalid event filter | event channel received a non-event filter (market or asset) | Use params: { event } or omit params entirely |
invalid timestamp | Auth timestamp is malformed | Send Unix seconds as a string |
timestamp expired | Auth timestamp is outside ±60s of server time | Resync clock and retry |
invalid signature | Auth HMAC signature does not match | Recompute the signature (see Overview) |
invalid api key | API key is unknown | Check the key |
api key expired | API key has passed its expiry | Issue a new key |
internal error | Server-side failure during subscribe, unsubscribe, or auth | Retry the request; if persistent, report the issue |
Operational Guidance
- Treat auth failures as non-retryable until credentials/signature are refreshed.
- Treat unsupported channel/market errors as configuration bugs, not transient failures.
- Log full error payloads for diagnostics.
- Reconnect with backoff only for transport-level failures.
See GET /error-codes for the full list of REST API error codes.