---
url: >-
  https://game-engine-io.github.io/enginex-frontend-sdk/concepts/compliance-errors.md
---
# Compliance errors

When the player is self-excluded, has pending KYC or is over a limit, several operations
fail with a compliance code. This page tells you **what to show** in each case. The complete
reference of all codes (typical status, methods) is in
[Error codes](/concepts/error-codes); the format of `EnginexError` is in [Errors](/concepts/errors).

::: warning Decide by `code`, never by `status`
Several of these codes arrive as **HTTP 500** (the gateway only gives its own category to some errors from the
compliance service). Related codes do not share a status (e.g. `SELF_EXCLUDED` is 422, while `COOLING_OFF` and
`ACCOUNT_BLOCKED` arrive as 500 when launching a game). Always use `isEnginexError(error, 'CODE')`.
:::

## Codes and what to show

| Code                      | What to show                                                                     | Where it appears                                                    |
| ------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `SELF_EXCLUDED`           | "You are self-excluded." No gaming action; link to help and, if there is one, the date in `responsibleGambling.getLimits()` | `login`, launching a game (casino) |
| `COOLING_OFF`             | "You are in a cooling-off period." Show when the pause ends (`selfExclusion.until`) | launching a game; may also appear on bets (not verified)     |
| `ACCOUNT_BLOCKED`         | "Your account is blocked." Direct them to contact support; do not retry           | `login`, launching a game                                           |
| `KYC_REQUIRED`            | "Verify your identity to continue" with the button to the KYC screen              | `deposits.createPix`, `withdrawals.request`/`confirmOtp`            |
| `KYC_PENDING`             | "We are reviewing your documents"; no resubmission                                | operations that require KYC                                         |
| `KYC_REJECTED`            | The reason (`kyc.getStatus().rejectionReason`) and the request to resubmit        | operations that require KYC                                         |
| `DEPOSIT_LIMIT_EXCEEDED`  | "You have reached your deposit limit" and how much remains (`getLimits().deposit`) | `deposits.createPix`                                               |
| `BET_LIMIT_EXCEEDED`      | "Amount above the bet limit"; ask for a smaller amount                            | sports bets                                                         |

`WITHDRAWAL_LIMIT_EXCEEDED` (withdrawal) follows the same pattern as the deposit.

::: info What is verified
Only **launching a game** (casino) is confirmed in the code as failing with `SELF_EXCLUDED`,
`COOLING_OFF` and `ACCOUNT_BLOCKED`. The "Where it appears" column for the other cases (deposit, withdrawal, bet)
is what is expected from the gateway's design and **was not verified** in the compliance service.
:::

For the KYC screen see
[Identity verification](/flows/kyc); for limits and self-exclusion, [Responsible gaming](/flows/responsible-gaming).

```ts
import { isEnginexError } from '@getenginex/sdk'

function complianceMessage(error: unknown): string | undefined {
  if (isEnginexError(error, 'SELF_EXCLUDED')) return 'You are self-excluded.'
  if (isEnginexError(error, 'COOLING_OFF')) return 'You are in a cooling-off period.'
  if (isEnginexError(error, 'ACCOUNT_BLOCKED')) return 'Your account is blocked. Contact support.'
  if (isEnginexError(error, 'KYC_REQUIRED')) return 'Verify your identity to continue.'
  if (isEnginexError(error, 'KYC_PENDING')) return 'We are reviewing your documents.'
  if (isEnginexError(error, 'KYC_REJECTED')) return 'Your verification was rejected. Submit the documents again.'
  if (isEnginexError(error, 'DEPOSIT_LIMIT_EXCEEDED')) return 'You have reached your deposit limit.'
  if (isEnginexError(error, 'BET_LIMIT_EXCEEDED')) return 'Amount above the bet limit.'
  return undefined // not a compliance error: handle it as a generic error
}
```

Do not show `error.message` as is: the text comes from the gateway, in English or without product context.
Show your own message (and translate it) based on the `code`.

## Unconfirmed operation (`UNKNOWN` with a 2xx status) {#unconfirmed-operation}

A single rule: **`UNKNOWN` with a 2xx `status` = unconfirmed operation: re-read the state before trying
again.** The gateway responded with HTTP success, but without confirming the operation, so it may have
happened or not. The SDK never delivers a result as if it had succeeded. `error.message` is the
gateway's message when it comes, otherwise the SDK's (`kyc.uploadDocument: ...`, `loyalty.redeem: ...`);
always decide by `code` + `status`, not by the text.

| Method                 | `status` | Re-read with            | Then                                       |
| ---------------------- | -------- | ----------------------- | ------------------------------------------ |
| `kyc.uploadDocument`   | 201      | `kyc.getStatus()`       | only resubmit if the document does not appear |
| `loyalty.redeem`       | 200      | `loyalty.get()`         | only repeat if the points were not deducted |

```ts
function unconfirmed(error: unknown): boolean {
  return isEnginexError(error, 'UNKNOWN') && error.status >= 200 && error.status < 300
}
```

## 429 and `retryAfter`

Besides `DEPOSIT_LIMIT_EXCEEDED` (which also comes out with status 429, but is a limit **on the player**, not
on requests), the gateway has a global request limiter. Its 429 comes **outside the
envelope** (`{ "error": "rate limit exceeded", "limit": 100, "reset_at": ..., "retry_after": 12 }`)
with the `Retry-After` header. The SDK converts it into an `EnginexError` with `code: 'RESOURCE_EXHAUSTED'`,
`status: 429` and `retryAfter` in **seconds**:

```ts
try {
  await enginex.kyc.getStatus()
} catch (e) {
  if (isEnginexError(e, 'RESOURCE_EXHAUSTED')) {
    setTimeout(retry, (e.retryAfter ?? 5) * 1000) // wait before trying again
  }
}
```

The SDK does **not** repeat the request on its own; the app decides. `retryAfter` comes from the
`Retry-After` header; without the header, it is `undefined`: use an interval of your own. Do not confuse it with
`DEPOSIT_LIMIT_EXCEEDED`: waiting does not resolve a player limit.
