Errors & notices

Errors reject a command or report a service failure. Notices are asynchronous messages about an open stream.

Error frame

An error carries the id of the command that caused it:

{
  "op": "error",
  "id": 1,
  "code": "not_on_plan",
  "feature": "detail_full",
  "message": "..."
}

Code	Meaning	Client action
unauthorized	Key is missing, unknown, or revoked	Stop and provide a valid key
key_revoked	Key was revoked while the connection was open	Close the connection and rotate the key
invalid_params	Unknown/missing parameter or value outside its allowed set	Fix the command; do not retry unchanged
invalid_address	mint or wallet is not a Solana address	Validate the address locally
invalid_mint	Address exists but is not a token mint	Use a token mint
unknown_stream	Stream name does not exist	Use one of the eight documented names
duplicate_subscription	An identical subscription is already open	Reuse the existing subscription
subscription_limit	Plan's open-subscription limit is exhausted	Unsubscribe or upgrade
connection_limit	Plan's concurrent-connection limit is exhausted	Close another connection or upgrade
rate_limited	Command rate is too high	Back off before retrying
not_on_plan	Requested feature is outside the plan	Inspect feature; remove it or upgrade
internal_error	Service failed while processing the command	Retry with backoff; report persistent failures

not_on_plan features

feature is one of:

• stream
• detail_full
• include_raw
• cursor
• candles
• candle_interval
• quota

The human-readable message includes a link to the pricing page. Branch client logic on code and feature, not on the message text.

Notice frame

A notice is not tied to a command. It reports stream state and normally carries the affected subscription:

{
  "op": "notice",
  "code": "gap",
  "sub": "tt_1",
  "message": "..."
}

Code	What happened	Client action
gap	Cursor is older than the replay window; delivery starts live	Record the gap and continue
replay_rate_limited	Replay allowance is exhausted; delivery starts live	Continue without replay
dropped	Client read too slowly and events were lost; cursor is the first lost event	Record the gap, narrow filters, or speed up consumption
quota_exceeded	Free monthly traffic quota is exhausted	Wait for the next period or upgrade
slow_consumer	Reading is consistently behind; connection is closing	Reconnect only after fixing consumption speed
server_restart	Service is restarting	Reconnect with backoff and the last processed cursor

dropped is emitted once per loss series. Repeated notices mean the subscription should be narrowed with filters or consumed faster.

Retry policy

Use exponential backoff with jitter for internal_error, restarts, and network disconnects. Do not automatically retry malformed commands, invalid keys, or plan denials unchanged.