Errors
Every error carries a stable code. Match on the code, never on the message text.
Error location
Wallet routes: /api/account, /api/balance/*, /api/round-ended
{ "error": "SESSION_EXPIRED" }
Everything under /api/v1/
{ "statusCode": 403, "message": "session 6f1e… expired", "data": null, "error": "SESSION_EXPIRED" }
Request validation failures on wallet routes use the code Bad Request with status 400. On envelope routes the same failure carries error: "Bad Request" and a message array listing each invalid field.
Catalogue
Authentication
| Code | Status | Cause | Action |
|---|---|---|---|
AUTHENTICATION_FAILED | 403 | No token, unknown token, revoked, or past its expiry. The relay deliberately does not say which. | Check the header and the token value. Ask the platform team whether the token is still active. |
GROUP_NOT_ACTIVE | 403 | The game provider has been suspended. | Contact the platform team. |
Session and game
| Code | Status | Cause | Action |
|---|---|---|---|
SESSION_EXPIRED | 403 | The session does not exist or has passed its one-day lifetime. | End the game session. The casino must relaunch the player. Owed credits go through the retry route. |
SESSION_GAME_MISMATCH | 400 | gameId in the request differs from the session's game. | Integration defect: the id passed from the frontend is wrong. |
SESSION_CURRENCY_MISMATCH | 400 | currency in the request differs from the session's. | Use the currency from session validation. |
GAME_NOT_FOUND | 404 | The session names a game id not in the registry. | Platform-side data problem. Contact the platform team. |
GAME_NOT_OWNED_BY_GROUP | 403 | The game belongs to a different game provider than the token. | Wrong token, or the game was registered under another game provider. |
GAME_NOT_ACTIVE | 403 | The game is registered but disabled. | Contact the platform team. |
Casino
| Code | Status | Cause | Action |
|---|---|---|---|
PROVIDER_NOT_FOUND | 404 | The casino referenced by the session or by providerIds no longer exists. | Refresh the casino id list. No further action. |
PROVIDER_NOT_ACTIVE | 403 | The casino is disabled on the platform. | Stop play for that casino's sessions; not recoverable by the game. |
AUTHENTICATION_TOKEN_EXPIRED | 403 | The casino rejected the player's wallet token (their 403). | Treat as an expired session. |
FUND_WITHDRAW_FAILED | 400 | The casino refused the debit (their 400). Almost always insufficient funds. | Reject the bet and show the balance. |
CASHOUT_FAILED | 500 | The casino failed the debit with their 500. | Reject the bet. Log it; if it repeats, tell the platform team. |
INTEGRATION_TIMED_OUT | 408 | The casino did not answer within 10 seconds. | Repeat the identical request with the same transactionId. For credits, schedule a retry. |
PROVIDER_API_FAILURE | 502 | The casino returned a status outside the contract. | Bet: reject. Credit: retry later. |
INVALID_PROVIDER_RESPONSE | 502 | The casino answered 200 with a body that does not match the contract. | Same as above. The relay did not trust the body, so treat the outcome as unknown and use the idempotent replay. |
Transactions
| Code | Status | Cause | Action |
|---|---|---|---|
TRANSACTION_IN_FLIGHT | 409 | Another request with the same transactionId is still waiting for the casino (less than 60 seconds old). | Wait one to two seconds and repeat the identical request. Do not change the id. |
Bad Request | 400 | Body or query failed validation: missing field, wrong type, unknown reason, more than two decimals, empty providerIds. | Fix the request. The casino was not called and nothing was recorded. |
Reporting
| Code | Status | Cause |
|---|---|---|
ROUND_NOT_FOUND | 404 | No round for that casino and round id in the calling game provider. |
TRANSACTION_NOT_FOUND | 404 | No transaction for that casino and transaction id in the calling game provider. |
Decision guide
Is the outcome known?
200: yes, success. 400, 403, 404, 500: yes, it did not happen. 408, 502, network error, client-side timeout: unknown.
Unknown outcome
Repeat the identical request with the same transactionId. The relay either replays the recorded success or makes one clean new attempt. Repeat with back-off until a definite answer arrives.
Definite failure on a credit
The player is owed money. Keep the full request body and retry through /api/balance/cash-in/retry on a schedule until it succeeds. Alert an operator if it does not succeed within the agreed tolerance.
Definite failure on a bet
Nothing was taken. Reject the bet in the game and, for FUND_WITHDRAW_FAILED, refresh the displayed balance with GET /api/account.