hizi docs

Appearance

Handling Lost Responses and Retry Scenarios ​

This appendix provides guidance for common edge cases where a response to a transactional call (e.g., addWin, doTransactions) is lost due to network issues, leaving your system in an uncertain or "stuck" state. Always prioritize querying status over blind retries to maintain idempotence and avoid issues like double-crediting.

Key Principles:

  • Do not retry 4xx errors (e.g., errorCode 15: GAMEROUNDNOTSTARTED), as they indicate the operation cannot proceed (e.g., round already closed).

  • Use querying calls like getGameRoundInfo or reconcileTransactions to confirm state before acting.

Step-by-Step Handling for Lost Responses:

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

  2. Query the round status:

    • Use POST /getGameRoundInfo with the gameRound ID.

  3. Based on the query:

    • If status="closed" and transactions match your expectation (e.g., win added and collected), treat as success—no further action needed.

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

  4. Retries: Only retry original calls on 5xx errors

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

  • Your system sends addWin but receives no response.

  • Query with getGameRoundInfo.

  • 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 15, the round was never started—start a new one if needed.

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

Note that From the V2 calls are only idempodent on gameround / transaction (gamestate) hashes until the gameround is closed. In that case repeated calls would be treated as a call on a non open gamerounds and therefore will fail!