Wallet error codes¶
| Status Code | Error Code | Description |
|---|---|---|
| 400 | error.general | unknown issue/internal server error |
| 400 | error.request.invalid | Client passed invalid request parameters |
| 400 | error.user.not-found | Player was not found |
| 400 | error.retry.incorrect | Appears when retried transaction differs from original transaction |
| 400 | limit.exceeded | Internal limits exceeded |
| 400 | decline.limit.conflict | Regulator or tax limits exceeded |
| 400 | decline.parent.notfound | Parent transaction was not found |
| 400 | decline.parent.failed | Parent transaction was found but it was failed |
| 400 | decline.balance.conflict | Unexpected error with balances |
| 400 | decline.player.blocked | Player was blocked (Temporary error) |
| 400 | decline.lowbalance | Insufficient funds |
| 400 | decline.restrictions | Regulator restriction |
| 400 | decline.client.custom | Operator-specific decline. Pair with error.details.localizedMessage to surface a player-language reason in the iFrame. Sent only on bet placement transactions where the original request carried context.language (details). |
Note
We expect the 'decline.player.blocked' error to be temporary for settle/resettle/cancelsettle transactions, as the bet should ultimately reach a final settled state.
Returning balances on decline.lowbalance
On a decline.lowbalance error, your wallet may include the player's current balances in the error body — same nested structure (platform → product → currency → balance details) as in a successful transaction response.
Why it helps: by default, after a decline.lowbalance the Sportsbook BE calls get-user-balance to show the player the amount available for placing a bet in the iFrame. If your error response already carries balances, the Sportsbook BE uses them directly and skips that follow-up call — fewer round-trips and less load on your wallet.
The field is optional and may also be included on other errors, but decline.lowbalance is the case where it provides a measurable benefit. See Returning balances in error responses for the schema and a full example.