Errors and money states
The wallet error codes a casino returns, the errors of the launch API, and what the player is shown about their money.
Three kinds of error meet in an integration:
- Wallet error codes that the casino's wallet returns to the RGS.
- Launch API errors that the RGS returns to the casino's backend.
- Player-facing errors that the game shows the player, each with a money state saying what happened to the bet. These are what a casino's support hears about.
Wallet error codes
A wallet refuses by answering HTTP 2xx, signed, with "status": "error" and one of these codes. Any other
code, and any refusal sent with a non-2xx status, is an unknown outcome: see
the overview.
{ "status": "error", "code": "LIMIT_EXCEEDED", "reason": "loss_limit", "message": "You have reached your daily loss limit" }| Code | Meaning | On a debit | On a credit | On a rollback |
|---|---|---|---|---|
INSUFFICIENT_FUNDS | Not enough money. | Void; player sees ERR_IPB. | Definite refusal: attention queue. | Definite refusal: attention queue. |
LIMIT_EXCEEDED | A responsible-gaming or other limit. | Void; ERR_GLE with your reason. | Attention queue. | Attention queue. |
PLAYER_BLOCKED | Blocked or self-excluded. | Void; ERR_GLE, reason yours or blocked. | Attention queue. | Attention queue. |
SESSION_EXPIRED | The player's session ended. | Void; ERR_IS. | Attention queue. | Attention queue. |
LOCATION | Not allowed where the player is. | Void; ERR_LOC. | Attention queue. | Attention queue. |
BET_REJECTED | The casino's rules refuse this bet. Definitely not debited, do not retry. | Void; ERR_BET_REJECTED with reason, message, details. | Attention queue. | Attention queue. |
NOT_FOUND | No such transaction. | Void; ERR_GEN. Use it to refuse a debit that was already rolled back. | Attention queue. | Done: nothing to return. |
DUPLICATE | The transaction exists, outcome not stated. | Unknown: rolled back. | Unknown: repeated. | Unknown: repeated. |
| any other | — | Unknown: rolled back. | Unknown: repeated. | Unknown: repeated. |
"Attention queue" means the RGS stops retrying and the round waits for an RGS operator, who repeats the
call or marks it settled after the casino confirms the money by hand. A credit or rollback should never
get there: accept them whatever the player's state. HTTP 401 and 403 are neither: on a debit they void
the round with ERR_GEN; on a credit or rollback they put the round in the attention queue at once and the
RGS stops retrying it until the keys are fixed and an operator retries the round.
Every refusal may carry:
| Field | Limit | Where it goes |
|---|---|---|
reason | 64 bytes kept | To the game client as reason. An open list. |
message | 512 bytes kept | To the game client as operatorMessage, shown as text. |
details | 16 string entries, keys up to 64 bytes, values up to 256 | With BET_REJECTED only, to the game client as details, shown as text. |
Launch API errors
The launch API answers an error with this body:
{
"error": "ERR_VAL",
"message": "currency is not offered",
"details": { "reason": "currency", "retryable": false },
"requestId": "4f1c2a9e-8d3b-4b8e-9a51-2f0c6d7e1a33"
}On POST /sessions, once the request passes authentication and its body parses with a non-empty requestId, the error's requestId is the body's. Otherwise it is your X-Request-Id header when you send one, or one the RGS made up. Quote it when
you ask about a failure.
| HTTP | error | details.reason | When |
|---|---|---|---|
| 400 | ERR_VAL | body | The body cannot be read, is larger than 1 MiB, or is not JSON. |
| 400 | ERR_VAL | empty | requestId, player.id or gameId is missing. |
| 400 | ERR_VAL | currency | The market does not offer the player's currency. |
| 400 | ERR_VAL | game | The game is not available on the market. |
| 400 | ERR_VAL | request_id | The requestId was already used for another launch, or for a session that can no longer be launched. |
| 400 | ERR_VAL | session_id | The session id in the path is not valid. |
| 400 | ERR_VAL | market | The market is missing: marketId of a session, market of the catalog. |
| 400 | ERR_VAL | limit, cursor | Catalog: limit or cursor not valid. |
| 400 | ERR_ATE | market | The market is unknown or does not belong to the calling key. |
| 400 | ERR_LOC | country | The market does not allow the player's country. |
| 400 | ERR_GLE | stake_limit | The player's stake limit is below the market's smallest bet. |
| 400 | ERR_WALLET_NOT_CERTIFIED | wallet | The market is closed: the casino's wallet has no current conformance pass. A player with an open round may still launch to finish it. |
| 400 | ERR_IS | empty | Reissue: the session does not exist, is not yours, or is closed. |
| 400 | ERR_IS | launched | Reissue: the session was already opened. |
| 401 | ERR_ATE | timestamp, signature, scope, address | Authentication failed: see Authentication and signing. |
| 500 | ERR_MAINTENANCE | front, schema | The game's client (front) or schema (schema) has not passed its check. Retryable. |
| 500 | ERR_GEN | empty | A failure on the RGS side. Retryable with the same requestId. |
details.retryable is true only on 500. A 400 will fail again until the request changes.
Player-facing errors
When a game call fails, the game client receives a failure with these fields:
| Field | Meaning |
|---|---|
error | One of the codes below. |
message | The RGS's short English description. |
reason | A finer reason: the RGS's (stake_limit, min_cycle, debit_unknown, …) or the casino's own. |
money | What happened to the player's money: see Money states. |
retryable | Whether repeating the same call may succeed. |
operatorMessage | The casino's message from the wallet, as is. |
details | The casino's details from a BET_REJECTED, as key and value pairs sorted by key. |
error | HTTP | Cause | Usual money |
|---|---|---|---|
ERR_VAL | 400 | Invalid bet, mode, action or parameters. | not_charged, or in_round for an action inside a round |
ERR_ATE | 401 | The game could not authenticate. | none |
ERR_IS | 401 | Session invalid or expired; the wallet answered SESSION_EXPIRED. | not_charged, or none outside a bet |
ERR_LOC | 403 | Location refused; the wallet answered LOCATION. | not_charged |
ERR_BNF | 404 | Round not found. | none, or in_round |
ERR_BE | 409 | A round is already open: the game resumes it. | in_round |
ERR_OUTCOME_UNKNOWN | 409 | A repeat of a request too old to answer. Nothing was done now; look up what the first call did. | none |
ERR_IPB | 422 | The wallet answered INSUFFICIENT_FUNDS. | not_charged |
ERR_GLE | 422 | A limit: the stake limit, the minimum time between rounds, or the wallet's LIMIT_EXCEEDED / PLAYER_BLOCKED. | not_charged |
ERR_BET_REJECTED | 422 | The wallet answered BET_REJECTED. | not_charged |
ERR_MAINTENANCE | 503 | The game's version is suspended or not available, or the casino's wallet is not certified. | not_charged |
ERR_GEN | 503 if retryable, else 500 | A failure in the RGS, the game or the wallet: the wallet was unavailable, its answer was unknown, or it answered NOT_FOUND, 401 or 403 to a debit; or the settlement of the player's saved progress is still being credited (reason state_settling). | not_charged, pending, refunded, or none |
What the player sees for each code is the game's choice. The game client tells the game to offer a top-up on
ERR_IPB, to resume on ERR_BE, to refresh on ERR_BNF, to stop on ERR_IS, ERR_ATE, ERR_LOC and
ERR_MAINTENANCE, and to show a message otherwise.
How a casino's own words reach the player
Take a bet over a bonus's cap. The wallet answers the debit:
{
"status": "error",
"code": "BET_REJECTED",
"reason": "bonus_max_bet",
"message": "Your bonus allows a bet of up to 5.00 GBP",
"details": { "max_bet": "5.00", "currency": "GBP", "bonus_id": "b-81" }
}The RGS voids the round without a rollback, and the game receives:
| Field | Value |
|---|---|
error | ERR_BET_REJECTED |
message | bet was refused |
reason | bonus_max_bet |
money | not_charged |
retryable | false |
operatorMessage | Your bonus allows a bet of up to 5.00 GBP |
details | bonus_id = b-81, currency = GBP, max_bet = 5.00 |
A game that knows the reason may word its own message from details; for a reason it does not know
it shows operatorMessage as it is. The player can try a smaller bet. The same path carries reason and
message of every other wallet refusal: a LIMIT_EXCEEDED with reason: loss_limit reaches the game as
ERR_GLE, reason: loss_limit, with your text in operatorMessage.
Money states
Every player-facing failure of a call that could move money says what happened to it:
money | Meaning | What the casino's ledger shows | What support should tell the player |
|---|---|---|---|
not_charged | The bet was not taken. | No debit for the round, or none applied. | Nothing was taken from your balance. You can try again once the cause (funds, limit, session) is fixed. |
refunded | The bet was taken, or may have been, and has been returned. | {roundId}:debit:1 and {roundId}:rollback:1 for the same amount, or only the rollback with nothing returned. | The round did not take place and your stake is back on your balance. |
in_round | The stake is in a round that is still open. | {roundId}:debit:1, no credit yet. | Your stake is in an unfinished round. Open the game again to finish it; if you do not, it is closed automatically and any win is paid. |
pending | The RGS does not know yet. A credit or rollback is still being settled. | The debit, and the credit or rollback not yet applied. | Your round is being settled and your balance will update; nothing is lost. The RGS keeps retrying until your wallet confirms. |
A missing money means the RGS does not state it. On ERR_OUTCOME_UNKNOWN and ERR_BNF nothing was done now, and what an
earlier call did must be looked up in the round's history; on ERR_GEN, look the round up. See
Jackpots, history and replay.
pending that does not clear within minutes means the credit or rollback is failing on the wallet's side:
check the wallet's answers to that transactionId. The RGS repeats it until it gets a final answer, and
after 10 attempts or 5 minutes its operators see the round in their attention queue. Do not change the
player's balance by hand while the RGS is still retrying: the next retry would apply on top of it. Agree a
manual fix with the RGS operators, who then mark the round settled.
A successful round whose credit is still being retried is not an error: the game gets its result without a balance and shows the balance as pending until the credit is done.