Error Handling

Error Response Format

All error responses use the Twirp format with an api_code in the meta field:

{
  "code": "invalid_argument",
  "msg": "Player has not enough funds to process an action.",
  "meta": {
    "api_code": "100",
    "api_message": "Player has not enough funds to process an action.",
    "balance": "50.00"
  }
}

Field	Type	Required	Description
code	string	Yes	Twirp error code (see below)
msg	string	Yes	Human-readable error description
meta.api_code	string	Yes	Numeric API error code
meta.api_message	string	Yes	API error message
meta.balance	string	Conditional	Current balance — required when api_code is 100, 105, or 106

Twirp Error Codes

Only two Twirp codes are used:

Twirp Code	HTTP Status	Meaning
invalid_argument	400	Client error (bad request, auth failure, business rule violation)
internal	500	Server error

Danger

Only HTTP 400 and 500 are used. Do not return HTTP 403, 409, 412, or other status codes.

---

API Error Codes

Funds-Related Codes (balance required in response)

api_code	Description	Operator Action
100	Insufficient funds	Return current balance in meta. Beexar shows “not enough funds” to player.
105	Bet limit exceeded	Return current balance in meta.
106	Win limit exceeded	Return current balance in meta.

Player Errors

api_code	Description	Operator Action
101	Player not found or disabled	Beexar terminates the session.

Request Errors

api_code	Description	Operator Action
400	Bad request	Malformed JSON, missing required fields.
403	Invalid signature	HMAC-SHA256 signature mismatch. Verify AUTH_TOKEN.
155	Transaction tombstoned	The id_provider was already rolled back. Reject the action.

Server Errors

api_code	Description	Operator Action
500	Internal server error	Generic server failure. Beexar will retry.

---

Retry Strategy (Beexar Side)

When Beexar receives an error or timeout from the operator’s wallet:

Response	Beexar Behavior
HTTP 200	Success, no retry
HTTP 400, api_code 100	Insufficient funds — no retry, show error to player
HTTP 400, api_code 403	Signature error — no retry (configuration issue)
HTTP 400, api_code 155	Tombstoned — no retry, action already cancelled
HTTP 400, other	Bad request — no retry (logged)
HTTP 500	Server error — retry with exponential backoff
Timeout	No response — retry with exponential backoff

Retry Parameters

Parameter	BetWin	Rollback	Finish
Max attempts	4 (1 + 3 retries)	Unlimited	Unlimited
Initial backoff	100 ms	10 s	10 s
Max backoff	400 ms	1 hour	1 hour
Backoff multiplier	2x	2x	2x
Total time budget	5 s	Up to 7 days	Up to 7 days

Note

Rollback and finish operations are processed asynchronously. They are retried with exponential backoff until the operator’s server responds successfully. This means your wallet will eventually receive every rollback and finish call, even if your server is temporarily down.

Caution

Every retry uses the same id_provider. Your wallet must handle repeated requests idempotently — return the original successful response if the transaction was already processed.

What Happens When Retries Are Exhausted

Action	Behavior on failure
BetWin	Error returned to player. The round is considered “not started” — no rollback is sent.
Rollback	Retried via the outbox worker (async, up to 7 days). Rollbacks are critical for financial consistency.
Finish	Retried via the outbox worker (async, up to 7 days). Finish is informational — financial actions already completed.

Tip

Beexar does not automatically send a rollback after a failed BetWin. Since Beexar cannot confirm whether the operator processed the request, sending a rollback could be incorrect. Instead, Beexar relies on idempotency: if the operator did process the bet, the next retry with the same id_provider will return the original response.

---

Timeout Handling (Operator Side)

Recommendations

1. Process quickly — aim for response times under 500ms
2. Return early — validate and respond before heavy background processing
3. Handle retries gracefully — same id_provider = return original response (idempotency)
4. Never block on external calls — if your wallet depends on downstream services, implement circuit breakers

What Happens on Timeout

sequenceDiagram
    participant Beexar
    participant Wallet as Operator Wallet

    Beexar->>Wallet: POST /betwin (id_provider: "tx_1")
    Note right of Wallet: Server slow / timeout
    Beexar->>Wallet: POST /betwin (retry 1, same id_provider)
    Note right of Wallet: Still no response
    Beexar->>Wallet: POST /betwin (retry 2, same id_provider)
    Note right of Wallet: Still no response
    Beexar->>Wallet: POST /betwin (retry 3, same id_provider)
    Note right of Wallet: Still no response
    Note over Beexar: All retries exhausted — error shown to player

Note

This is why idempotency is critical. If your server eventually processes “tx_1” after all retries have failed, the funds are deducted but Beexar is unaware. Monitor your wallet for unmatched transactions.

---

Best Practices

1. Always return valid JSON — even on errors, return the Twirp error format
2. Include balance on funds-related codes — api_codes 100, 105, 106
3. Log all requests — include id_provider, round_id, and account_id for debugging
4. Monitor response times — alert if P99 exceeds 1 second
5. Implement health checks — Beexar may check endpoint availability