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.
Codes the server sends
Section titled “Codes the server sends”| 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 |
Codes the client raises
Section titled “Codes the client raises”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 |
Game codes
Section titled “Game codes”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.
Close codes
Section titled “Close codes”| 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 |
