Skip to content

Error codes

Every failed request rejects with a ShoehiveError. Its source is "shoehive" for the codes on this page and "game" for codes your game raised with reject(). The lists are read from the source code; the descriptions come from the wire protocol, and the build fails if the two disagree.

Code When details
BAD_REQUEST Malformed message, unknown request type, request before hello
UNSUPPORTED_PROTOCOL hello.v not supported { supported: number[] }
UNAUTHORIZED Session no longer valid (for example token revoked)
FORBIDDEN Not allowed for this player, for example player.rename by an authenticated player, or table.create past a table limit { limit: number } (table limits)
NOT_FOUND Unknown game or table { kind: 'game' | 'table' }
INVALID_OPTIONS Table options failed the game's options schema { issues: StandardSchemaIssue[] }
INVALID_INPUT Action input failed its schema { issues: StandardSchemaIssue[] }
NOT_JOINED Request needs the table to be joined first
TABLE_FULL No free seat
SEAT_TAKEN Requested seat is occupied or reserved
ALREADY_SEATED Player is at the game's per-player seat limit
NOT_SEATED Action or seat.leave from a player without a seat
NOT_STARTED Action before the table started (only preStart actions allowed)
ACTION_NOT_ALLOWED Unknown action, or not allowed in the current phase { phase: string | null }
ALREADY_SUBMITTED A once action was already submitted this round
NOT_PARTICIPANT Round action from a seat that is not part of the current round (for example it sat down mid-round)
ROUND_CLOSED Round action after the round closed
STALE_REVISION act.rev did not match { rev: number } (current)
TABLE_ENDED Action on an ended table
TABLE_UNAVAILABLE The table is faulted (for example a store write failed, or recovery hit a game version mismatch) until an operator reloads it
RATE_LIMITED Connection exceeded its rate limit { retryAfterMs: number }
TIMEOUT An async action (for example a wallet call) exceeded its time budget and was rolled back
WALLET_UNAVAILABLE The wallet backend failed and game code did not handle it; the action was rolled back
INTERNAL Game code threw something other than reject(). The action was rolled back. In production the message is generic

shoehive/client raises these locally. Servers never send them.

Code When
CONNECTION_LOST The socket closed while the request was waiting for its ack
REQUEST_TIMEOUT No ack within requestTimeoutMs (default 15 000)
CLIENT_CLOSED client.close() was called while the request was waiting

Codes passed to reject(code, details?) must match /^[A-Z][A-Z0-9_]*$/ and must not reuse a code above. Reusing one is a type error, and a runtime error if types are bypassed.

Code Meaning Client should
1000 Normal close Not reconnect
1001 Server shutting down or restarting Reconnect with backoff and resume
1009 Message larger than maxMessageBytes Fix the client; not reconnect in a loop
4000 No hello within 10 s Reconnect
4001 Unsupported protocol version Not reconnect; upgrade the client
4002 Repeated protocol violations Not reconnect in a loop
4401 Session revoked or unauthorized Re-authenticate, then reconnect without resume
4409 Kicked by an operator Not reconnect automatically
4429 Severe rate-limit abuse Back off for at least 30 s