Errors

Format#

API responses have an envelope. On error, the HTTP status is the same statusCode as in the body and the stable code is in error.code:

JSON

{
  "success": false,
  "message": "Este merchant opera em BRL; use o merchant de MXN do seu grupo",
  "statusCode": 403,
  "error": { "code": "CURRENCY_NOT_ENABLED" }
}

Decide by error.code; the message is text for people (in Portuguese) and may change.

Validation error (422)#

A body or query that does not match the schema has its own format, with the list of invalid fields:

JSON

{
  "data": null,
  "status": 422,
  "error": "VALIDATION_ERROR",
  "message": "Erro de validação",
  "details": [{ "path": "/player_id", "message": "Expected string" }]
}

Catalog#

Authentication (all routes)#

HTTP	Code	Cause
401	`MISSING_AUTH_HEADERS`	`X-Merchant-Id`, `X-Timestamp`, `X-Nonce` or `X-Signature` is missing.
401	`REQUEST_EXPIRED`	`X-Timestamp` outside the 5-minute window.
401	`INVALID_MERCHANT`	Unknown merchant.
401	`MERCHANT_BLOCKED`	Merchant is blocked.
401	`INVALID_SIGNATURE`	The signature does not match.
401	`IP_NOT_ALLOWED`	Source IP not in the merchant list.
401	`NONCE_REUSED`	Repeated nonce.
503	`AUTH_UNAVAILABLE`	Temporary failure; resend with a new nonce.

Game launch#

HTTP	Code	Cause
400	`UNSUPPORTED_CURRENCY`	Currency not in the supported list.
400	`INVALID_COUNTRY`	Country is not a valid ISO 3166-1 alpha-2 code.
403	`CURRENCY_NOT_ENABLED`	Currency differs from the merchant currency.
403	`PRODUCT_NOT_ENABLED`	The game product is not enabled.
404	`GAME_NOT_FOUND`	Game does not exist or is inactive.
409	`WALLET_NOT_CONFIGURED`	Merchant without `walletUrl`.
409	`AMBIGUOUS_GAME`	Code exists in more than one provider; send `provider`.
422	`PROVIDER_NOT_SUPPORTED`	Provider without a launch integration.
500	`LAUNCH_GAME_FAILED`	Internal error.
502	`LAUNCH_FAILED`	The provider did not open the game.

Queries#

HTTP	Code	Route
400	`INVALID_RANGE`	`GET /v1/reports/ggr`: `from` is not before `to`.
400	`RANGE_TOO_LARGE`	`GET /v1/reports/ggr`: period longer than 93 days.
500	`GGR_REPORT_FAILED`	`GET /v1/reports/ggr`
500	`LIST_GAMES_FAILED`	`GET /v1/games`
500	`LIST_PROVIDERS_FAILED`	`GET /v1/providers`
500	`LIST_TRANSACTIONS_FAILED`	`GET /v1/transactions`

Your wallet replies#

Codes your wallet returns in { "ok": false, "error": "..." } (see Seamless wallet):

Code	When to use
`INSUFFICIENT_FUNDS`	Not enough balance for the bet.
`PLAYER_NOT_FOUND`	Unknown player.
`PLAYER_BLOCKED`	Player is blocked.
`TRANSACTION_NOT_FOUND`	`refund`/`rollback` of a transaction you never applied.
`INVALID_SIGNATURE`	Callback with an invalid signature (reply HTTP 401).

Retries#

Situation	Can you resend?
5xx, timeout, network error	Yes, with a new `X-Nonce` and `X-Timestamp`.
`AUTH_UNAVAILABLE` (503)	Yes, with a new nonce.
`REQUEST_EXPIRED`	Yes, after fixing the clock.
Other 4xx	No — fix the request.

A failed launch leaves nothing pending: just open it again.