Skip to main content
Section 8

FAQ

Common problems​

Issues raised most often during integrations, with the usual cause first.

Requests to the relay time out or the connection is refused, with no JSON body​

This is a network-level failure, not a relay error. The relay always answers with JSON, even on failure, so a bare TCP timeout, a connection reset, or an HTML error page from a gateway means the request never reached it. The usual cause is IP allowlisting: the platform only accepts traffic to the relay from egress addresses the game provider has registered. Common variants:

  • The game backend's egress IP changed after a redeploy, a scale-out, or a move to a new region, and the new address was never sent to the platform team.
  • Traffic leaves through a NAT gateway or proxy whose address differs from the server's own.
  • Staging addresses were registered, production ones were not.

The fix is to send the platform team the complete list of egress addresses per environment, ideally as fixed ranges. A quick check from the affected host is curl -i {RELAY_BASE_URL}/api/healthz: a JSON 200 means the network path is fine and the problem is elsewhere.

The relay answers 408 INTEGRATION_TIMED_OUT​

Here the request did reach the relay; it is the casino that did not answer within 10 seconds. If it happens for one casino only and persistently, the casino has usually not allowlisted the relay's own egress addresses, or its wallet endpoint is down. The platform team handles this with the casino; the game provider's side is only to repeat the request with the same transactionId and, for credits, to keep the retry running.

403 AUTHENTICATION_FAILED although the token is correct​

  • The header is Authorization: Bearer <token>. A missing Bearer prefix, or the token in a header with another name, fails.
  • The token was copied with a trailing newline or space. Tokens are compared byte for byte after the Bearer prefix.
  • A staging token is being used against the production relay, or the reverse. Tokens are issued per environment.
  • A gateway or WAF in front of the game backend strips the Authorization header on outgoing calls. Send the token as x-service-token instead.
  • The token was revoked or reached its expiry date. The platform team can confirm by the token prefix, which is the first characters of the token and safe to share.

SESSION_EXPIRED immediately after launch​

A session lives for a day, so an expiry seconds after launch means the relay did not find the id it was given. Usual causes:

  • The launch went through the staging launcher while the game backend calls the production relay, or the reverse. The two environments do not share sessions.
  • The frontend altered the sessionId in transit: URL-decoding twice, trimming at a dash, or reading the wrong query parameter when the game's own frontendUrl also carries parameters.
  • The launch was replayed from a bookmarked or cached redirect URL after the session had actually expired. Players must be relaunched from the casino lobby.

400 on a money route with only { "error": "Bad Request" }​

Wallet routes follow the casino wire format, which has no room for field-level detail, so the body names no field. The relay does log the failing fields, and the platform team can look them up by x-correlation-id. The causes seen in practice, in order:

  • amount or betAmount with more than two decimals, typically the result of floating-point arithmetic such as 0.1 + 0.2. Round before serialising.
  • amount sent as a string, or negative.
  • appliedMultiplier missing on a cash-in. It is required on every credit, including losses and refunds, where it is 0.
  • reason outside the documented list, including lowercase spellings.
  • providerIds on round-ended sent as a single string rather than an array, or as an empty array.
  • An empty or missing body, often because the HTTP client was configured with the wrong content type.

Unknown top-level fields are not the cause: the relay ignores fields it does not know. Game-specific data belongs in the game object, where it is stored with the round.

SESSION_GAME_MISMATCH for some players only​

The gameId in the request differs from the one the session was launched with. This appears when several titles share one frontend and the frontend hard-codes a game id, or when casinos launch the same title under different ids. The gameId forwarded on the redirect and confirmed by session validation is the one to use for that session.

A cash-in for a finished round fails with SESSION_EXPIRED​

The live session has passed its one-day lifetime, typically because a credit was retried hours or days later. Use POST /api/balance/cash-in/retry with the same body; that route can resolve the session from the archive for up to two months. A plain cash-in cannot.

The balance returned differs from what the casino shows​

  • The relay rounds every balance to two decimals, half-up. A casino displaying more precision will differ in the last digits.
  • The balance is read live from the casino on every /api/account call; nothing is cached. A difference that persists is on the casino side.
  • On a replayed transactionId the balance returned is the one recorded when the movement originally succeeded, not the current balance.

404 PROVIDER_NOT_FOUND on round-ended​

providerIds takes the casino identifiers exactly as returned by GET /api/v1/providers/ids or by session validation: 24-character hexadecimal strings. Casino names, slugs or internal identifiers from the game provider's own configuration are not accepted. Because every id is resolved before any notification goes out, one bad id fails the whole call.

No casinos appear in the catalog or the id list​

The catalog only lists casinos that have configured at least one of the game provider's games; the id list only contains casinos registered on the platform. Both empty on a new integration is normal until the platform team has set up the first casino. On staging, the sandbox casino has to be registered and configured for the game before a launch can succeed.

Does the relay retry towards casinos or queue anything?​

No. Each request is forwarded once. Retries, back-off and reconciliation are the game backend's responsibility, using the idempotency rules on the round lifecycle page.

How are environments separated?​

Staging and production have different relay and launcher URLs, different tokens, different casinos and separate sessions. Nothing created on one is visible on the other. Both must be allowlisted separately if IP restrictions are in place.

Support requests​

A problem report should include: the environment, the exact path, the transactionId or roundId, the sessionId, the response body received, and the time in UTC. If an x-correlation-id, was sent, include it; it lets the platform team find the request in their logs immediately.