Errors

When a request fails, the RGS returns a non-2xx HTTP status with a structured error body instead of a Result. The client should map the code to a player-facing message.

Error Shape

Game-logic and wallet failures surface the shared Error object (common.Error):

Field	Type	Meaning
`category`	enum	Broad bucket — see below.
`code`	enum	The specific reason. Switch on this.
`message`	string	Human-readable detail (e.g. "max bet is 50.00"). Not for display as-is.

{
  "category": "ERROR_CATEGORY_OPERATOR",
  "code": "ERROR_CODE_INSUFFICIENT_FUNDS",
  "message": "balance too low"
}

Category	When
`ERROR_CATEGORY_VALIDATION`	The request was malformed or out of range (bad amount, missing param, unknown action).
`ERROR_CATEGORY_OPERATOR`	The operator wallet rejected the bet (no funds, disabled player, currency/session issues).
`ERROR_CATEGORY_ROUND`	The round state forbids the action (round closed, voided, already in progress, an open round exists).

Codes

Validation

Code	Meaning
`ERROR_CODE_INVALID_MESSAGE`	The `message` couldn't be parsed as the game's `Query`.
`ERROR_CODE_INVALID_AMOUNT`	The wager string isn't a valid decimal.
`ERROR_CODE_INVALID_PARAM`	A parameter is missing or invalid (e.g. neither `over` nor `under` for Dice).
`ERROR_CODE_PARAM_OUT_OF_RANGE`	A parameter failed validation (e.g. rows/mine count outside allowed bounds, bet over the limit).
`ERROR_CODE_INVALID_REQUEST_TYPE`	The `oneof` variant isn't valid for this game (e.g. `reveal` on a single-action game).

Operator / Wallet

Code	Meaning
`ERROR_CODE_INSUFFICIENT_FUNDS`	Player balance can't cover the wager.
`ERROR_CODE_PLAYER_DISABLED`	The operator has disabled this player.
`ERROR_CODE_SESSION_EXPIRED`	The wallet session is no longer valid.
`ERROR_CODE_WRONG_CURRENCY`	Currency mismatch against the player's account.
`ERROR_CODE_OPERATOR_REJECTED`	Generic wallet rejection.
`ERROR_CODE_DEBIT_FAILED`	The debit call to the operator failed.

Round

Code	Meaning
`ERROR_CODE_ROUND_NOT_FOUND`	No round matches the supplied `roundId`.
`ERROR_CODE_ROUND_CLOSED`	The round is already settled — no further actions allowed.
`ERROR_CODE_ROUND_VOIDED`	The round was voided.
`ERROR_CODE_ACTION_IN_PROGRESS`	A previous action on this round is still being processed.
`ERROR_CODE_ACTIVE_ROUND_EXISTS`	Can't start (or rotate seeds) while a round is open. Resume or finish it first.

Bet Limits

Before debiting, the RGS rejects bets whose worst-case payout exceeds the operator's configured limit — returned as ERROR_CODE_PARAM_OUT_OF_RANGE with the max allowed bet in message. Side bets (e.g. Blackjack Perfect Pairs) and mid-round actions (e.g. a Mines reveal that would push the next payout over the limit) are checked independently. Surface these as "max bet exceeded" / "cash out to continue" prompts.

Transport-Level Errors

Auth, session, and lookup failures (handled before game logic) come back as plain HTTP errors with a code string — e.g. 401 missing_token / session_not_found, 404 round_not_found, 503 round_initializing. Treat 401 as "session gone" (re-launch) and retry 503 round_initializing after a short delay.

Provably Fair

Game Codes & RTP