Validation
Request limits, response formats, idempotency rules, and errors that require reconciliation.
On this page
Request rules#
Send JSON to POST /v1/commands with X-API-Key. Method names are case-sensitive. Unknown methods and fields are rejected. Legacy api_login, api_password, and user_password compatibility fields are stripped; they do not authenticate a request. New integrations should omit them.
Currency support is code-based: three uppercase letters, enabled for the workspace, with provider/game coverage. There is no fixed small list. Player usernames are nonblank, 1–128 characters with no control characters. Game IDs are at most 255 characters and should be copied exactly from the catalogue.
Launch URLs supplied by you must be absolute HTTPS URLs without embedded credentials, with each exact origin allowlisted. balance is a finite JSON number from 0 through 1000000000. Free-round limits and provider-specific options are documented on their method pages.
Responses#
Require HTTP success and numeric error: 0 before using a result. Successful command responses are not wrapped in data. A numeric nonzero error with message is an application rejection and may arrive with HTTP 200. Gateway errors use an object:
{
"error": {
"code": "CURRENCY_NOT_ALLOWED",
"message": "Currency is not enabled for this organization",
"requestId": "request-id"
}
}Keep the x-request-id response header. Normalized numeric application-error bodies may not include a request ID; gateway-error objects include it.
Idempotency and recovery#
| Method | Idempotency-Key |
|---|---|
createPlayer, getGame, addFreeRounds, deleteFreeRounds, deleteAllFreeRounds | Required |
getGameList, getGameDemo, getFreeRounds | Rejected |
Keys are 8–255 printable ASCII characters without spaces. Persist one key per operation with its exact request before sending; do not reuse it for changed fields or another player. Completed results can be replayed only while safely retained. Sensitive launch results can be unavailable for replay.
On a timeout or UPSTREAM_OUTCOME_UNKNOWN, inspect Request Logs and contact support. The same key may return IDEMPOTENCY_OUTCOME_UNKNOWN, IDEMPOTENCY_RESULT_UNAVAILABLE, or IDEMPOTENCY_RESULT_EXPIRED. A new key is not a recovery mechanism. Keep player funds reserved until reconciliation determines whether the original operation took effect.
Common gateway errors#
| Code | Meaning / next step |
|---|---|
INVALID_API_KEY, IP_NOT_ALLOWED, SCOPE_DENIED | Check key validity, egress IP allowlist, and method scope |
CURRENCY_NOT_ALLOWED, GAME_NOT_ALLOWED | Check workspace currency and game/provider entitlement |
RETURN_ORIGIN_NOT_ALLOWED | Allowlist the exact HTTPS origins of both return URLs |
CALLBACK_NOT_CONFIGURED | Configure callback URL and signing secret |
STARTING_BALANCE_REQUIRED | Supply the numeric starting balance for getGame |
ACTIVATION_REQUIRED, PRODUCTION_ACTIVATION_REQUIRED | Check demo or production activation entitlement |
INSUFFICIENT_GGR_BALANCE | Fund the separate workspace GGR wallet |
IDEMPOTENCY_KEY_REQUIRED, INVALID_IDEMPOTENCY_KEY, IDEMPOTENCY_NOT_SUPPORTED | Correct the header for the method |
IDEMPOTENCY_CONFLICT | The key belongs to a different request; reconcile the original operation |
REQUEST_IN_PROGRESS | An identical operation is still processing; do not dispatch a new one |
UPSTREAM_APPLICATION_ERROR | The provider returned a conclusive rejection |
UPSTREAM_OUTCOME_UNKNOWN, IDEMPOTENCY_OUTCOME_UNKNOWN | Reconcile before another financial operation |
IDEMPOTENCY_RESULT_UNAVAILABLE, IDEMPOTENCY_RESULT_EXPIRED | Prior result cannot be safely replayed; inspect logs and reconcile |
Rate, quota, and capacity restrictions depend on workspace and key configuration. Follow any Retry-After header, and retain mutation identity when waiting. To get help, provide request ID, timestamp, game, player, currency, and settlement serial number when relevant. Never send API keys, callback secrets, or temporary launch URLs in a support ticket.
Worked diagnostic examples#
HTTP 200, but the game did not launch#
A response such as {"error": 1, "message": "Request rejected"} is an illustrative application failure, not a launch success. Check the numeric error before reading a launch URL. Save the actual message and x-request-id; distinguish a conclusive rejection from an unknown outcome before changing the wallet reservation. Do not treat every HTTP 200 response as a successful debit. See the launch contract and backend examples.
A launch timed out after funds were reserved#
Suppose the backend persisted operation launch-20261101-001, reserved the player's funds, and sent getGame, but no response arrived. A timeout does not prove the provider rejected the launch. Retain the exact request, original idempotency key and reservation. Inspect request logs and reconcile with support before releasing funds or creating another launch. If the same key reports an unknown, expired or unavailable result, changing the key still does not resolve the original operation. Include this scenario in your integration acceptance checks.
A settlement fails signature verification or arrives twice#
If valid-looking JSON fails verification, check whether middleware parsed and reserialized it before calculating HMAC-SHA256. Whitespace changes alter the signed bytes: verify x-callback-signature against the exact raw request body using the configured secret. Never bypass verification to clear a delivery queue.
After verification, deduplicate by serial_number in the same durable transaction as the wallet update. A repeated serial must not apply a second credit. Use credit_amount as the authoritative post-round balance rather than reconstructing it from bet and win amounts. Follow the settlement contract for acknowledgement and recovery behavior.