Skip to content

Rollback and Retry Logic

This page describes the critical requirements for rollback handling and retry behavior for all transaction types.

Rollback Requirements

Critical: Rollback Error Handling

Proper rollback handling is MANDATORY for system integrity. If a rollback cannot be processed, you MUST return one of these specific error codes:

  • decline.parent.notfound - Parent transaction does not exist in your system
  • decline.parent.failed - Parent transaction exists but failed (e.g., insufficient funds)

Never return generic errors for rollback failures. The system relies on these specific codes to handle rollback scenarios correctly.

Infinite Retries for Rollback

If your wallet returns anything other than HTTP 200 or HTTP 400 with a valid error body for a rollback request, the system will retry indefinitely until it receives a definitive response.

Why? The system must confirm the final state of the transaction. Temporary errors (5XX, timeouts, network issues) cannot leave transactions in an uncertain state.

Action required: Ensure your rollback endpoint is highly available and always returns either:

  • HTTP 200 with success response
  • HTTP 400 with decline.parent.notfound or decline.parent.failed

Rollback Validation Requirements

When processing a rollback transaction (type: rollback):

  1. Verify parent transaction exists using context.parentId
  2. Check parent transaction status:
    • If parent not found → Return decline.parent.notfound
    • If parent failed → Return decline.parent.failed
    • If parent succeeded → Process rollback normally

Rollback Example

Standard bet rollback:

Rollback Request
{
  "id": "5f338453-6172-491f-b8f0-27e382ea05eb_rollback",
  "currency": "USD",
  "platform": "sport",
  "type": "rollback",
  "createdAt": "2025-01-29T00:35:10Z",
  "initiatedAt": "2025-01-29T00:35:10Z",
  "context": {
    "product": "sportsbook",
    "reason": "sport rollback",
    "betId": "5f338453-6172-491f-b8f0-27e382ea05eb",
    "parentId": "5f338453-6172-491f-b8f0-27e382ea05eb"
  },
  "amountBreakdown": {
    "cash": "13.9",
    "locked": "0",
    "bonus": "0"
  }
}
Rollback Response
{
  "id": "5f338453-6172-491f-b8f0-27e382ea05eb_rollback",
  "currency": "USD",
  "platform": "sport",
  "type": "rollback",
  "createdAt": "2025-01-29T00:35:10Z",
  "initiatedAt": "2025-01-29T00:35:10Z",
  "context": {
    "product": "sportsbook",
    "reason": "sport rollback",
    "betId": "5f338453-6172-491f-b8f0-27e382ea05eb",
    "parentId": "5f338453-6172-491f-b8f0-27e382ea05eb"
  },
  "amountBreakdown": {
    "cash": "13.9",
    "locked": "0",
    "bonus": "0"
  },
  "balances": {
    "sport": {
      "main": {
        "USD": {
          "cash": "100.0",
          "bonus": "0",
          "locked": "0",
          "retract": "0"
        }
      },
      "sportsbook": {
        "USD": {
          "cash": "100.0",
          "bonus": "0",
          "locked": "0",
          "retract": "0"
        }
      }
    }
  },
  "alreadyProcessed": false
}

Error response if parent not found:

Rollback Error - Parent Not Found
{
  "error": {
    "code": "decline.parent.notfound",
    "message": "Parent transaction 5f338453-6172-491f-b8f0-27e382ea05eb not found",
    "origin": "YourCompanyName"
  },
  "alreadyProcessed": false
}

Error response if parent failed:

Rollback Error - Parent Failed
{
  "error": {
    "code": "decline.parent.failed",
    "message": "Parent transaction 5f338453-6172-491f-b8f0-27e382ea05eb failed with insufficient funds",
    "origin": "YourCompanyName"
  },
  "alreadyProcessed": false
}

Retry Logic by Operation Type

Bet Placement (withdrawal)

Limited retries - Strict time limits for bet acceptance.

Response handling:

  • 200 → Transaction successful, bet accepted
  • 400 with correct error body → Transaction declined (e.g., insufficient funds), no retries
  • 5XX status codes or timeouts → Retry up to 3 times
  • After 3 failed retries → System initiates rollback request

Retry parameters for bet placement:

  • Retry count: 3 attempts
  • Triggered by: 5XX status codes or request timeouts
  • After retries exhausted → Rollback initiated

Rollback retry parameters:

  • Retry count: Unlimited (infinite retries)
  • Delay between retries: 5 minutes
  • 200 or 400 with correct body → Retry process ends
  • Other responses → Continue retrying indefinitely until definitive response

Rollback Infinite Retries

Rollback requests will retry forever until receiving HTTP 200 or HTTP 400 with valid error. This ensures transaction state is always confirmed. Make sure your rollback endpoint is highly available.

Parent transaction validation:

Your wallet must verify that the parent transaction (via context.parentId) exists. Return 400 with error code decline.parent.notfound if parent transaction is not found, or decline.parent.failed if parent transaction failed.

Settlement Operations (deposit)

Includes: settle, cancelsettle, resettle, cashout

Response handling:

  • 200 → Transaction successful
  • 400 with correct error body → Transaction declined, no retries
  • 5XX status codes or timeouts → Retry up to 1000 times

Retry parameters:

  • Retry count: 1000 attempts
  • Delay between retries: 1 minute
  • Triggered by: 5XX status codes or request timeouts

Response handling:

  • 200 or 400 with correct body → Transaction processed completely, no retries
  • 5XX or timeouts → Retry with above parameters
  • If 1000 retries reached → Bet blocked for operations until manual intervention by operations team

Bonus Operations (award/release)

Includes: bonus award, bonus release, freebet award, etc.

Retry parameters:

  • Retry count: 100
  • Delay between retries: 5 minutes

Response handling:

  • 200 or 400 with correct body → Transaction processed completely, no retries
  • 5XX or 408 status codes → Retry until success
  • Other responses → Retry with above parameters

Response Requirements Summary

Operation Type Success Response Error Response Retry Behavior
Bet Placement HTTP 200 HTTP 400 3 retries on 5XX/timeout, then rollback
Rollback HTTP 200 HTTP 400 with decline.parent.* Infinite retries (5 min delay)
Settlement HTTP 200 HTTP 400 1000 retries on 5XX/timeout (1 min delay)
Bonus HTTP 200 HTTP 400 100 retries, 5 min delay

Always Return Definitive Responses

For all operations, always return either HTTP 200 (success) or HTTP 400 (business error) with a valid error body. Avoid 5XX errors or timeouts as they trigger retries.

When to use 5XX responses:

Use HTTP 5XX only when absolutely necessary, such as:

  • Race condition scenario: A rollback request arrives while the parent transaction (bet placement) is still being processed due to technical delays. In this case, return HTTP 5XX to trigger retries until the parent transaction completes.
  • Temporary system unavailability: Database connection issues, service temporarily down, etc.

Do NOT use 5XX for:

  • Business logic errors (use HTTP 400 instead)
  • Validation failures (use HTTP 400 instead)
  • Parent transaction not found (use HTTP 400 with decline.parent.notfound)
  • Parent transaction failed (use HTTP 400 with decline.parent.failed)