hizi docs

Appearance

Handling Lost Responses and Retry Scenarios ​

This appendix gives guidance for common edge cases. In these cases, a response to a transactional call (for example, addWin, doTransactions) is lost because of a network issue. This leaves your system in an uncertain, or "stuck", state. Always query the status first. Do not retry blindly. This keeps the call idempotent (repeating the call produces the same result) and avoids issues like double-crediting.

Key Principles:

  • Do not retry 4xx errors. For example, errorCode 13 (GAMEROUNDNOTACTIVE) means the gameRound hash is known, but the round is already closed. These errors show that the operation cannot proceed.

  • Use a query call to confirm the state before you act. Use /getGameRoundInfo for an open round. Use /getGameRoundHistoryInfo for a closed round. /getGameRoundInfo fails once the round is closed. /getGameRoundHistoryInfo fails while the round is still open. If you do not know the round's state, try /getGameRoundInfo first. If it fails with errorCode 13, use /getGameRoundHistoryInfo instead.

Step-by-Step Handling for Lost Responses:

  1. If a response is lost (for example, timeout or network error), do not immediately retry the original call.

  2. Query the round status:

    • Use POST /getGameRoundInfo with the gameRound ID. If that fails with errorCode 13 (GAMEROUNDNOTACTIVE), the round has closed. Use POST /getGameRoundHistoryInfo instead.

  3. Based on the query:

    • If status="closed" and the transactions match what you expect (for example, win added and collected), treat this as success. Take no further action.

    • If status="open" but transactions show partial processing (for example, debit occurred but win not credited), close the round with endGameRound.

  4. Retries: Retry the original call only on 5xx errors.

Example Scenario: Lost Response to addWin (with collect=true)

  • Your system sends addWin but receives no response.

  • Query with getGameRoundInfo (fall back to getGameRoundHistoryInfo if the round has since closed).

  • If the response shows status="closed" and totalWinAmount matches, log as success.

  • If status="open", call endGameRound to close it cleanly.

  • If the query fails with errorCode 14 (GAMEROUNDNOTFOUND), the round was never started. Start a new one if needed.

If issues persist, contact support with full logs, including headers (for example, x-h-error-id).

Which calls are idempotent, and when ​

"Idempotent" means that sending the exact same call again produces the same result. The call does not apply a second time. This guarantee is not the same for every call. It only applies while the gameRound is still open:

  • voidGameRound is safe to retry. A repeat of an already-successful voidGameRound does not cause an error. It does not void the round a second time.
  • addWin does not currently deduplicate a retry. Suppose your first call succeeded, but you never saw the response, and the round is still open. In this case, resending the same addWin call adds the win a second time. Do not retry addWin blindly. Always query the round state first (see above). Resend the call only if the query shows the win is missing.
  • startGameRound, wagerWin, collectWin, and endGameRound likewise have no automatic deduplication. Follow the query-first flow above before resending any of them.

Once a gameRound is closed, none of these calls can be safely retried, not even the normally-safe ones. The system no longer tracks the round as open. Any call that references it fails with errorCode 13 (GAMEROUNDNOTACTIVE). At that point, use /getGameRoundHistoryInfo to confirm the final state. Do not retry the call.