Errors
The error format, every error code, whether to retry, and what to do.
Format
Errors return a non-2xx HTTP status and this body:
json
{
"code": 1201,
"error": "priceMismatch",
"message": "Amount 1.10 EUR is not the current price of level 2 for reel-triple at op-42.",
"retryable": false,
"level": 2,
"price": "1.00",
"serverTime": "2027-03-01T12:00:00.184Z",
"requestId": "req_5b1e..."
}- Branch on
code(stable) orerror(stable name), never onmessage. - Quote
requestIdin support requests. retryable: truecomes with aRetry-Afterheader (seconds) where applicable.1505also carriesnextPlayAt(UTC time),1201carrieslevelandprice(the level's current price, a decimal string), and1506carriesmaintenanceUntil(UTC time); no other code has extra fields.
A planned maintenance window refuses a play like this (HTTP 503, Retry-After set to the seconds until maintenanceUntil):
json
{
"code": 1506,
"error": "maintenance",
"message": "reel-triple is under planned maintenance until 2027-03-01T14:00:00.000Z.",
"retryable": false,
"maintenanceUntil": "2027-03-01T14:00:00.000Z",
"serverTime": "2027-03-01T12:00:00.184Z",
"requestId": "req_5b1e..."
}The rule for bets
- 4xx (except 429): definite. The bet was not played. Refund and don't retry the same request. That includes
1507settlementSuspendedand1508sideGameOff. - 429 and 5xx: not definite. Retry the same request with the same
betId. - The one exception is
1506maintenance. It is HTTP503but it is a definite answer: the bet was not played and the body hasretryable: false. Refund and don't retry thatbetId.
Codes
| Code | Name | HTTP | Retry? | Meaning and action |
|---|---|---|---|---|
| 1000 | invalidSignature | 401 | No | Signature mismatch. Check the canonical string against the test vectors. |
| 1001 | timestampOutOfRange | 401 | After fixing the clock | Timestamp outside ±60 s. Compare with serverTime; fix NTP (Network Time Protocol). |
| 1002 | nonceReused | 401 | With a new nonce | The nonce was already used. |
| 1003 | keyNotValid | 401 | No | Unknown, expired or revoked key, or request from a non-allowlisted IP. Contact us. |
| 1100 | operatorNotAllowed | 403 | No | The operatorId is not the code of an enabled Operator of your Partner. |
| 1101 | gameNotEnabled | 403 | No | The game isn't enabled for this Operator or currency. |
| 1103 | unblockNotAllowed | 403 | No | The player's block was set by another Partner. Only the Partner that set a block can lift it. |
| 1200 | validationFailed | 400 | No | Malformed or missing field, or a level that isn't one of the levels offered to the Operator (GET /v1/partner/games/{gameId}/levels lists them); details in message. |
| 1201 | priceMismatch | 400 | No | The level is offered but the amount isn't its current price. The body returns level and the current price. Refund, then send a new bet with a new betId at that price. Prices can change after a configuration publication: read GET /v1/partner/games/{gameId}/levels. |
| 1202 | currencyNotSupported | 400 | No | The currency isn't offered to the Operator (it is not enabled, it is excluded for the Operator, it is the demo currency FUN on a real session or bet, or no exchange rate has been stored for it yet), or it doesn't match the session. |
| 1203 | betTooOld | 400 | No | betCreatedAt is beyond the bet age limit. Refund. |
| 1204 | betInFuture | 400 | No | betCreatedAt is in the future. Fix your clock. |
| 1300 | sessionExpired | 410 | No | Create a new session; a relaunch of an expired or closed session is refused too. (Retries of earlier bets still return their results.) |
| 1301 | sessionNotFound | 404 | No | Unknown session token. |
| 1302 | sessionReplaced | 409 | No | A newer session for this Partner, Operator, player and game exists. Use it. |
| 1400 | betIdReuse | 409 | No | Same betId with a different request. Never reuse a betId. |
| 1401 | betNotFound | 404 | No | A look-up of a betId we hold no record of at this moment. It is not a final answer: the bet may still be on its way to us. Cancel it (POST /v1/partner/bets/{betId}/cancel) and refund only when cancel returns cancelled. |
| 1402 | betInProgress | 409 | Yes, after Retry-After | A look-up of a bet we accepted that isn't final yet. Look it up again, or retry the original bet with the same betId. A look-up never finishes or cancels a bet. |
| 1500 | exposureLimitReached | 403 | No | The Operator's risk limit is reached. Contact the Operator. |
| 1501 | playerBlocked | 403 | No | The player is blocked (see Compliance). |
| 1502 | gameUnavailable | 403 | No | The game version is disabled in this jurisdiction (an emergency stop), or a progressive game has no jackpot for the bet currency (a Real currency with no Real jackpot set up, or a fun currency the Operator does not offer). The first bet in a fun currency the Operator offers creates its jackpot and does not get this error. |
| 1503 | complianceRejected | 403 | No | The Operator's jurisdiction profile is missing or cannot be used, so the bet is refused (fail closed). Contact support. Details in message. |
| 1504 | demoNotAllowed | 403 | No | Demo isn't allowed for this Operator's jurisdiction. |
| 1505 | roundTooSoon | 403 | No | The player's minimum round interval hasn't passed (it applies across all sessions and both streams). The body has nextPlayAt. Skip the play before you debit, or refund if you already debited. Use a new betId for a later play. |
| 1506 | maintenance | 503 | No (definite) | The game is in a planned maintenance window for this Operator. The bet was not played: refund it. The body has maintenanceUntil (UTC) and retryable: false, and Retry-After is the seconds until then. Do not retry this betId; send new plays, with new betIds, only after maintenanceUntil. Session create and relaunch are refused with 1506 as well. Read maintenance on GET /v1/partner/games to hide the game in advance. |
| 1508 | sideGameOff | 403 | No (definite) | The player switched the side game off in the widget, or the widget is hidden, so the bet was refused. ReelXtra decides this. No Round was made: refund the bet amount and don't retry that betId. Stop sending bets until ready.enabled or optInChanged says the side game is on again. A retry of a bet we already accepted still returns its result. |
| 1507 | settlementSuspended | 403 | No (definite) | ReelXtra staff have suspended the Operator (or its Group) for non-payment, so new plays into its Network Pools are refused. The bet was not played: refund it and don't retry that betId. There are no extra fields. Retries of accepted bets, look-ups, cancels and history still work, and fixed-prize games and Operator-owned Pools are not affected. Staff suspend and lift a suspension by hand, and a change takes effect on the next configuration publication. Send new plays only after the suspension is lifted; your account manager will tell you. |
| 1600 | rateLimited | 429 | Yes | Slow down; honour Retry-After. Also returned when a session is relaunched too often. |
| 9000 | internalError | 500 | Yes | Retry the same request. |
| 9001 | serviceUnavailable | 503 | Yes | Unplanned outage or overload, a request that took too long, a bet we could not confirm (retry with the same betId; we finish the bet we stored and never play it twice), or (on the endpoints that take a nonce) a short refusal after a server left our cluster: honour Retry-After and, for a nonce endpoint, retry with a new timestamp and nonce. Planned maintenance is 1506. |
Statuses that are not errors
These come back with HTTP 200 in a bet, cancel or look-up response:
status | Do |
|---|---|
committed | Credit win. |
voided | Refund the bet amount. The bet was undone by us (for example, it was unfinished after a server failure). |
cancelled | Refund the bet amount. The bet was cancelled before it committed. |
Unknown paths, even when correctly signed, return 404 with the body below. It has no numeric code, and it is the same for every unknown path and method:
json
{ "error": "notFound", "requestId": "req_..." }