API docs v1
Aggregator API · v1

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:

json
{
  "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#

MethodIdempotency-Key
createPlayer, getGame, addFreeRounds, deleteFreeRounds, deleteAllFreeRoundsRequired
getGameList, getGameDemo, getFreeRoundsRejected

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#

CodeMeaning / next step
INVALID_API_KEY, IP_NOT_ALLOWED, SCOPE_DENIEDCheck key validity, egress IP allowlist, and method scope
CURRENCY_NOT_ALLOWED, GAME_NOT_ALLOWEDCheck workspace currency and game/provider entitlement
RETURN_ORIGIN_NOT_ALLOWEDAllowlist the exact HTTPS origins of both return URLs
CALLBACK_NOT_CONFIGUREDConfigure callback URL and signing secret
STARTING_BALANCE_REQUIREDSupply the numeric starting balance for getGame
ACTIVATION_REQUIRED, PRODUCTION_ACTIVATION_REQUIREDCheck demo or production activation entitlement
INSUFFICIENT_GGR_BALANCEFund the separate workspace GGR wallet
IDEMPOTENCY_KEY_REQUIRED, INVALID_IDEMPOTENCY_KEY, IDEMPOTENCY_NOT_SUPPORTEDCorrect the header for the method
IDEMPOTENCY_CONFLICTThe key belongs to a different request; reconcile the original operation
REQUEST_IN_PROGRESSAn identical operation is still processing; do not dispatch a new one
UPSTREAM_APPLICATION_ERRORThe provider returned a conclusive rejection
UPSTREAM_OUTCOME_UNKNOWN, IDEMPOTENCY_OUTCOME_UNKNOWNReconcile before another financial operation
IDEMPOTENCY_RESULT_UNAVAILABLE, IDEMPOTENCY_RESULT_EXPIREDPrior 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.