JRGS Casino API

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:

  1. Wallet error codes that the casino's wallet returns to the RGS.
  2. Launch API errors that the RGS returns to the casino's backend.
  3. 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" }
CodeMeaningOn a debitOn a creditOn a rollback
INSUFFICIENT_FUNDSNot enough money.Void; player sees ERR_IPB.Definite refusal: attention queue.Definite refusal: attention queue.
LIMIT_EXCEEDEDA responsible-gaming or other limit.Void; ERR_GLE with your reason.Attention queue.Attention queue.
PLAYER_BLOCKEDBlocked or self-excluded.Void; ERR_GLE, reason yours or blocked.Attention queue.Attention queue.
SESSION_EXPIREDThe player's session ended.Void; ERR_IS.Attention queue.Attention queue.
LOCATIONNot allowed where the player is.Void; ERR_LOC.Attention queue.Attention queue.
BET_REJECTEDThe 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_FOUNDNo such transaction.Void; ERR_GEN. Use it to refuse a debit that was already rolled back.Attention queue.Done: nothing to return.
DUPLICATEThe 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:

FieldLimitWhere it goes
reason64 bytes keptTo the game client as reason. An open list.
message512 bytes keptTo the game client as operatorMessage, shown as text.
details16 string entries, keys up to 64 bytes, values up to 256With 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.

HTTPerrordetails.reasonWhen
400ERR_VALbodyThe body cannot be read, is larger than 1 MiB, or is not JSON.
400ERR_VALemptyrequestId, player.id or gameId is missing.
400ERR_VALcurrencyThe market does not offer the player's currency.
400ERR_VALgameThe game is not available on the market.
400ERR_VALrequest_idThe requestId was already used for another launch, or for a session that can no longer be launched.
400ERR_VALsession_idThe session id in the path is not valid.
400ERR_VALmarketThe market is missing: marketId of a session, market of the catalog.
400ERR_VALlimit, cursorCatalog: limit or cursor not valid.
400ERR_ATEmarketThe market is unknown or does not belong to the calling key.
400ERR_LOCcountryThe market does not allow the player's country.
400ERR_GLEstake_limitThe player's stake limit is below the market's smallest bet.
400ERR_WALLET_NOT_CERTIFIEDwalletThe market is closed: the casino's wallet has no current conformance pass. A player with an open round may still launch to finish it.
400ERR_ISemptyReissue: the session does not exist, is not yours, or is closed.
400ERR_ISlaunchedReissue: the session was already opened.
401ERR_ATEtimestamp, signature, scope, addressAuthentication failed: see Authentication and signing.
500ERR_MAINTENANCEfront, schemaThe game's client (front) or schema (schema) has not passed its check. Retryable.
500ERR_GENemptyA 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:

FieldMeaning
errorOne of the codes below.
messageThe RGS's short English description.
reasonA finer reason: the RGS's (stake_limit, min_cycle, debit_unknown, …) or the casino's own.
moneyWhat happened to the player's money: see Money states.
retryableWhether repeating the same call may succeed.
operatorMessageThe casino's message from the wallet, as is.
detailsThe casino's details from a BET_REJECTED, as key and value pairs sorted by key.
errorHTTPCauseUsual money
ERR_VAL400Invalid bet, mode, action or parameters.not_charged, or in_round for an action inside a round
ERR_ATE401The game could not authenticate.none
ERR_IS401Session invalid or expired; the wallet answered SESSION_EXPIRED.not_charged, or none outside a bet
ERR_LOC403Location refused; the wallet answered LOCATION.not_charged
ERR_BNF404Round not found.none, or in_round
ERR_BE409A round is already open: the game resumes it.in_round
ERR_OUTCOME_UNKNOWN409A repeat of a request too old to answer. Nothing was done now; look up what the first call did.none
ERR_IPB422The wallet answered INSUFFICIENT_FUNDS.not_charged
ERR_GLE422A limit: the stake limit, the minimum time between rounds, or the wallet's LIMIT_EXCEEDED / PLAYER_BLOCKED.not_charged
ERR_BET_REJECTED422The wallet answered BET_REJECTED.not_charged
ERR_MAINTENANCE503The game's version is suspended or not available, or the casino's wallet is not certified.not_charged
ERR_GEN503 if retryable, else 500A 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:

FieldValue
errorERR_BET_REJECTED
messagebet was refused
reasonbonus_max_bet
moneynot_charged
retryablefalse
operatorMessageYour bonus allows a bet of up to 5.00 GBP
detailsbonus_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:

moneyMeaningWhat the casino's ledger showsWhat support should tell the player
not_chargedThe 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.
refundedThe 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_roundThe 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.
pendingThe 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.

On this page