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, or room code expired/invalid. |
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
game is requiredYou forgot to include the game field in the request body.
Invalid game. Valid: chess, checkers, ...The game value is not one of the supported games.
players[] required for live and test sessionsYou must provide a players array for live/test mode.
subway-runner only supports matchType: botSubway Runner is single-player — use matchType: "bot".
Test API key cannot create live sessionsSwitch to your bg_live_ key for live sessions.
Missing Authorization headerAdd Authorization: Bearer <your-key> to the request.
Invalid or inactive API keyThe key doesn't exist or the tenant account is inactive.
Origin not allowed for this API keyAdd your origin to the allowlist in the dashboard.
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: 42Retry-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.