Error Codes

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.

Code	Meaning
`AUTH_REQUIRED`	Not authenticated
`AUTH_EXPIRED`	Session token expired
`AUTH_INVALID`	Invalid or malformed token
`ACCOUNT_NOT_LINKED`	Wallet not linked to a verified user account
`RATE_LIMITED`	Too many requests
`INTERNAL_ERROR`	Server error
`TABLE_NOT_FOUND`	Table ID doesn’t exist
`TABLE_FULL`	Table has no open seats
`GAME_NOT_FOUND`	Game type not hosted by this server
`INSUFFICIENT_BALANCE`	Not enough platform credits
`DUPLICATE_MESSAGE`	messageId already seen in this session
`VERSION_UNSUPPORTED`	Protocol version not supported

Game Errors

Sent via game_error message type with gameType and tableId. These indicate game-rule violations.

Code	Meaning
`INVALID_ACTION`	Action type not valid in current state
`INVALID_AMOUNT`	Bet/raise amount out of bounds
`NOT_YOUR_TURN`	Action sent when it wasn’t this client’s turn
`ROUND_COMPLETE`	Round already ended
`BETTING_WINDOW_CLOSED`	Submitted after window closed (phase-based games)
`TIMEOUT`	Client 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.

Fundamentals

Messages

Identity

Funding

Client Runtime

Advanced

Protocol Errors

Game Errors

Message Formats

Error Handling Guidance

​Protocol Errors

​Game Errors

​Message Formats

​Error Handling Guidance

Protocol Errors

Game Errors

Message Formats

Error Handling Guidance