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
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	The sub name is already in use on this connection	Pick another name, or reuse the subscription you have
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": "..."
}

Notices come in two kinds, and the difference is the only thing your reconnect logic needs from them: after the first kind the connection keeps working, after the second it is closing.

The connection keeps working

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

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

With quota_exceeded the connection and every subscription stay open — delivery simply stops until the next period, and new subscriptions are refused with not_on_plan and feature: "quota". There is no warning before the limit.

The connection is closing

The notice arrives immediately before the close frame, so it is the last thing you receive. Read the code before you decide whether to reconnect.

Code	What happened	Client action
ping_timeout	No pong and no command arrived within the read timeout	Answer server pings, or send {"op":"ping"} if a proxy drops them; then reconnect
slow_consumer	Reading is consistently behind	Reconnect only after fixing consumption speed
server_restart	Service is restarting	Reconnect with backoff and the last processed cursor
plan_changed	The plan on this account changed	Reconnect; the new limits apply from the next connection
key_revoked	The key was revoked while connected	Stop using it and rotate the credential
account_banned	The account is blocked	Do not reconnect; contact support
account_deleted	The account no longer exists	Do not reconnect

plan_changed is the one to handle deliberately: limits are read when a connection opens, so an upgrade takes effect on the next one. Reconnect and you have the new plan.

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.