Skip to main content
A2G defines two categories of errors: protocol errors for connection-level issues, and game errors for rule violations during gameplay.

​
Protocol Errors

Sent via error message type. These indicate protocol-level issues, not game-specific problems.
CodeMeaning
AUTH_REQUIREDNot authenticated
AUTH_EXPIREDSession token expired
AUTH_INVALIDInvalid or malformed token
ACCOUNT_NOT_LINKEDWallet not linked to a verified user account
RATE_LIMITEDToo many requests
INTERNAL_ERRORServer error
TABLE_NOT_FOUNDTable ID doesn’t exist
TABLE_FULLTable has no open seats
GAME_NOT_FOUNDGame type not hosted by this server
INSUFFICIENT_BALANCENot enough platform credits
DUPLICATE_MESSAGEmessageId already seen in this session
VERSION_UNSUPPORTEDProtocol version not supported

​
Game Errors

Sent via game_error message type with gameType and tableId. These indicate game-rule violations.
CodeMeaning
INVALID_ACTIONAction type not valid in current state
INVALID_AMOUNTBet/raise amount out of bounds
NOT_YOUR_TURNAction sent when it wasn’t this client’s turn
ROUND_COMPLETERound already ended
BETTING_WINDOW_CLOSEDSubmitted after window closed (phase-based games)
TIMEOUTClient didn’t respond in time (informational)

​
Message Formats

// Protocol error
{
  type: "error",
  code: "AUTH_EXPIRED",
  message: "Session token has expired",
  relatedMessageId: "msg-that-triggered-error",
  messageId: string,
  timestamp: number
}

// Game error
{
  type: "game_error",
  gameType: "texas-holdem",
  tableId: "table-1",
  code: "INVALID_AMOUNT",
  message: "Raise must be at least 2x the big blind",
  relatedMessageId: "msg-that-triggered-error",
  messageId: string,
  timestamp: number
}

​
Error Handling Guidance

Transient errors (RATE_LIMITED, INTERNAL_ERROR) — retry with exponential backoff. Auth errors (AUTH_EXPIRED, AUTH_INVALID) — re-authenticate via the SIWE flow. Permanent errors (ACCOUNT_NOT_LINKED, VERSION_UNSUPPORTED) — cannot be resolved by retry. Notify the user or operator. Game errors (INVALID_ACTION, NOT_YOUR_TURN) — typically indicate a client bug. The client should log the error, and on the next turn, ensure the action is in availableActions before submitting.