Reference/Error codes
Error codes
There are two kinds of error. The operator API answers with an HTTP status code and a code. On wallet callbacks, you report a business rule error with HTTP 200 and a code in the body.
API errors
The error body of the operator API carries code, message and request_id; depending on the code, details (e.g. details.source, details.fields, details.reason) and, on 429, retry_after are added. message is in English, or Turkish with Accept-Language: tr; build your logic on code. Quote the request_id (the same as the X-Boss-Request-Id response header) when you open a support request.
403API error body
{
"code": "GAME_DISABLED",
"message": "This game cannot be opened right now.",
"request_id": "req_01HF3Q2P",
"details": { "source": "site_rule" }
}| Code | HTTP | When |
|---|---|---|
| INVALID_SIGNATURE | 401 | Signature headers missing, or the signature could not be verified |
| TIMESTAMP_SKEW | 401 | X-Timestamp is outside ±30 s or not a number |
| CREDIT_LIMIT | 402 | Launch: credit limit exceeded |
| OPERATOR_SUSPENDED | 402 | Launch: operator suspended, or no production approval on Live |
| IP_NOT_ALLOWED | 403 | IP is not on the allowlist |
| SCOPE_MISSING | 403 | The key’s scope is not enough |
| MODULE_DISABLED | 403 | A required module is disabled (details.module; on launch details.source: module) |
| GAME_DISABLED | 403 | Launch: the game cannot be opened on this site; the reason is in details.source (Game launch) |
| SITE_DISABLED | 403 | Launch: the site is off, or a site called on Live is not in Live status |
| MARKET_RESTRICTED | 403 | Launch: no RTP variant is eligible under the site’s market rules |
| NOT_FOUND | 404 | No such record |
| REQUEST_ID_CONFLICT | 409 | Same X-Request-Id, different request |
| SITE_REQUIRED | 422 | Operator-wide key and several sites: site_id is needed |
| VALIDATION_ERROR | 422 | Missing or invalid field (details.fields), missing X-Request-Id (details.field) or a business rule (details.reason) |
| CURRENCY_NOT_SUPPORTED | 422 | Currency not supported |
| SCOPE_DENIED | 403 | The site or record is outside your key’s scope |
| PLAYER_BLOCKED | 403 | Launch: player restricted |
| FRAUD_CLOSURE | 403 | A game closed by a fraud rule cannot be opened through the API |
| COUNTRY_BLOCKED | 403 | Launch, demo, game detail: the game or the provider blocks the player’s country |
| COUNTRY_REQUIRED | 403 | Launch: the game has country restrictions and the player’s country is unknown; send country |
| DEMO_NOT_AVAILABLE | 404 | Demo: the provider offers no demo |
| REQUEST_IN_PROGRESS | 409 | The same X-Request-Id is still being processed; retry shortly |
| MANUAL_LOCKED | 409 | Stuck round: manual option before it unlocks. escalate first |
| ITEM_RESOLVED | 409 | Stuck round: the item is already resolved |
| APPROVAL_PENDING | 409 | Stuck round: an approval is pending |
| TX_NOT_RESENDABLE | 409 | Stuck round: the transaction cannot be resent in its current state |
| TX_CHANGED | 409 | Stuck round: the transaction changed in the meantime; read it again and decide |
| NO_TRANSACTION | 409 | Stuck round: the round has no suitable transaction for this resolution |
| CAMPAIGN_CLOSED | 409 | Free round: the campaign has finished or was cancelled |
| CAMPAIGN_CHANGED | 409 | Free round: the campaign changed status in the meantime (started or opened), retry |
| GRANT_CLOSED | 409 | Free round: the player’s grant is used, expired, cancelled or was rejected by the provider (details.status) |
| BUDGET_WARNING | 409 | Free round: with the added players the estimated cost exceeds the budget warning; your Owner adds them in the portal |
| FREEROUND_ADD_PLAYERS_UNSUPPORTED | 409 | Free round: the provider cannot add players to an open campaign |
| PROVIDER_CANCEL_UNSUPPORTED | 409 | Free round: the provider cannot cancel a single player; cancel the whole campaign |
| REFERENCE_CONFLICT | 409 | Free round: a campaign with different content was already created with the same reference |
| LAUNCH_TOKEN_EXPIRED | 410 | launch_url has expired or was used |
| INVALID_JSON | 422 | The body could not be read as JSON |
| INVALID_CURSOR | 422 | cursor did not come from a previous response |
| DATE_RANGE_INVALID | 422 | Report: from is not before to |
| DATE_RANGE_TOO_LONG | 422 | Report: the range is longer than 366 days; transaction feed: longer than 31 days (details.max_days) |
| DATE_IN_FUTURE | 422 | Daily reconciliation: totals cannot be sent for a future day |
| LIMIT_RANGE_INVALID | 422 | Limit: minimum above maximum, or zero |
| LIMIT_DEFAULT_INVALID | 422 | Limit: default bet outside the range |
| LIMIT_OUT_OF_RANGE | 422 | Limit: leaves the range of the upper level |
| TRANSACTION_REQUIRED | 422 | Stuck round: several open items, transaction_id is required |
| ACTION_NOT_ALLOWED | 422 | Stuck round: this resolution cannot be used for this issue |
| OUTCOME_NOT_ALLOWED | 422 | Stuck round: this outcome cannot be used for this issue |
| OPERATOR_CONFIRMATION_REQUIRED | 422 | Stuck round: cancelling a manually paid win needs operator_confirmed |
| TRANSACTION_MISMATCH | 422 | Stuck round: the transaction ID does not match the item |
| RATE_LIMITED | 429 | Per-minute request limit exceeded |
| PROVIDER_NOT_CONNECTED | 503 | Provider not connected |
| PROVIDER_UNAVAILABLE | 503 | Provider unreachable |
| MAINTENANCE | 503 | Maintenance |
| NOT_READY | 503 | /health/ready: the database or Redis is not answering, or the server is shutting down (details) |
Wallet reply codes
You return these codes. A business rule error goes out with HTTP 200; the body carries status: ERROR and a code. Add balance if you know it.
200Business rule error (HTTP 200 + code)
{
"status": "ERROR",
"code": "INSUFFICIENT_FUNDS",
"balance": 0.40
}| Code | Meaning | Use |
|---|---|---|
| INSUFFICIENT_FUNDS | Insufficient balance | bet; rollback when reversing a win |
| INVALID_TOKEN | Session invalid or expired | authenticate, balance, bet. Do not return it on win or rollback |
| INVALID_SIGNATURE | Signature could not be verified | All calls |
| DUPLICATE_TRANSACTION | Same transaction with different content | bet, win, rollback |
| PLAYER_BLOCKED | Player restricted / self-exclusion | All calls |
| LIMIT_EXCEEDED | Responsible gaming limit exceeded | bet, win, rollback |
| TRANSACTION_ROLLED_BACK | You hold a cancellation record for this transaction | bet, win. On rollback it means “already reversed” |
| INTERNAL_ERROR | Operator error | All calls |
Reply classes
Boss Hub puts every reply into one of three classes: clean OK, clean business rejection or uncertain. Uncertain means it is unknown whether money moved. On a bet, uncertainty is settled by an automatic rollback; win and rollback are retried on the schedule.
| Reply | Class | bet | win | rollback |
|---|---|---|---|---|
| 200 OK, ID and currency match | Clean OK | Accepted | Accepted | Accepted, source transaction reversed |
| 200 ERROR: INSUFFICIENT_FUNDS, LIMIT_EXCEEDED, PLAYER_BLOCKED, INVALID_TOKEN | Clean business rejection | Rejected | No retry, win_rejected item | No retry, rollback_rejected item |
| Same codes, an earlier attempt was uncertain | Uncertain | Automatic rollback | Retried on the schedule; then win_rejected | Retried on the schedule; then an item opens |
| TRANSACTION_NOT_FOUND (HTTP 409 or 200) | Clean business rejection for rollback | Treated as uncertain | Treated as uncertain | Contract violation, rollback_rejected item |
| TRANSACTION_ROLLED_BACK | Clean (cancellation record) | Rejected, warning | Rejected, win_rejected, warning | Counted as OK: already reversed |
| DUPLICATE_TRANSACTION | Uncertain | Automatic rollback, duplicate_conflict item | Schedule stops, duplicate_conflict item | Same as win |
| INVALID_SIGNATURE | Uncertain | Automatic rollback, alarm | Retried on the schedule, alarm | Same as win |
| Timeout, connection error, 5xx, INTERNAL_ERROR | Uncertain | Retried within the time budget, then automatic rollback | Retried on the schedule | Retried on the schedule |
| 200 but the body cannot be parsed, currency is missing or does not match, transaction_id does not match, or balance is invalid | Uncertain | Same + alarm | Same + alarm | Same + alarm |
| WAF 403, other 3xx and 4xx, 429 | Uncertain | Same | Same | Same |
| Unknown error code | Uncertain | Same + alarm | Same + alarm | Same + alarm |
Retry schedule
| Call | Schedule | When it ends |
|---|---|---|
| bet | Synchronous, no wait between attempts. First attempt + 2 retries, 3 s each (5 s and 3 retries can be selected in the portal). Total time budget of at most 20 s. | Automatic rollback |
| win | T0, +30 s, +2 min, +10 min, +30 min. 5 attempts in total. | The round becomes stuck after attempt 4; manual resolution after attempt 5 |
| rollback | Same as win. | bet_timeout item for a bet rollback, rollback_rejected item for a win rollback |
| win (amount 0) | Same as win; no retry after a rejection. | No item opens; the round and invoice are not affected |