> ## Documentation Index
> Fetch the complete documentation index at: https://a2g-protocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Protocol and game 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

```typescript theme={null}
// 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.