Errors

All errors return JSON with an error string. HTTP status codes follow standard REST conventions.

Error format

{ "error": "Origin not allowed for this API key" }

HTTP status codes

Status	Meaning	Common causes
`400`	Bad Request	Missing required fields, invalid game type, invalid matchType for game.
`401`	Unauthorized	Missing Authorization header, invalid or expired API key.
`403`	Forbidden	Origin not in allowlist, or test key used to create a live session.
`404`	Not Found	Session ID not found, room code expired/invalid, bot ID not found, or no active bots for auto-pick.
`409`	Conflict	Bot injection target session isn’t pending, player already in session, or room already full.
`429`	Too Many Requests	Rate limit exceeded for your plan. Back off and retry.
`500`	Internal Server Error	Something went wrong on our end. Contact support with the request ID.

Common error messages

400game is required

You forgot to include the game field in the request body.

400Invalid game. Valid: chess, checkers, ...

The game value is not one of the supported games.

400players[] required for live and test sessions

You must provide a players array for live/test mode.

400subway-runner only supports matchType: bot

Subway Runner is single-player — use matchType: "bot".

403Test API key cannot create live sessions

Switch to your bg_live_ key for live sessions.

401Missing Authorization header

Add Authorization: Bearer <your-key> to the request.

401Invalid or inactive API key

The key doesn't exist or the tenant account is inactive.

403Origin not allowed for this API key

Add your origin to the allowlist in the dashboard.

409Session is not pending

You tried to inject a bot into a session that's already active or ended.

404No active bots available for this tenant

Bot auto-pick found no registered bots for that game — register one via POST /v1/bots first.

409Room is already full

The session's room already has its full player count.

Rate limit headers

When you're approaching or have hit the rate limit, we include these headers:

X-RateLimit-Limit:     300
X-RateLimit-Remaining: 0
X-RateLimit-Reset:     1710000060
Retry-After:           42

Retry-After is in seconds. Wait that long before retrying. If you're consistently hitting limits, consider upgrading your plan.

Support

For 500 errors or unexpected behaviour, email support@beta-gamer.com with the full request/response and the timestamp. We aim to respond within 24 hours.

Beta Gamer GaaS API — questions? support@beta-gamer.com