# Retrieving Entitlements

### getEntitlementsConsumption

The user's current entitlement status can be retrieved by calling the `getEntitlementsConsumption` method. This retrieves information about the user's current level of entitlement as well as information about any entitlements consumed.

{% tabs %}
{% tab title="Swift" %}

```swift
do {
  let entitlements = try await entitlementsClient.getEntitlementsConsumption()
  // Handle entitlements
} catch {
  // Handle error
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
try {
  val consumption = entitlementsClient.getEntitlementsConsumption()
  // Handle consumption
}
catch (e: SudoEntitlements.EntitlementsException) {
  // Handle error
}
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
try {
  const consumption = await entitlementsClient.getEntitlementsConsumption()
  // Handle consumption
}
catch (err) {
  // Handle error
}
```

{% endtab %}
{% endtabs %}

The `getEntitlementsConsumption` method returns an `EntitlementsConsumption` object that specifies both the user's entitlements and any consumption of those entitlements.

Entitlements may be consumed by the user themselves or may be consumed by sub-resources of the user.

For example the `sudoplatform.sudo.max` entitlement controls the maximum number of Sudo Profiles a user may have at any one time. This entitlement is consumed at the user level. Conversely the `sudoplatform.virtual-cards.virtual-cardMaxPerSudo` specifies how many Sudo Virtual Cards may be active for any single Sudo Profile. Each Sudo Profile's consumption of this entitlement is listed separately in the `EntitlementsConsumption` object. Consumers are identified by an `id` (in the case of a Sudo Profile this is the Sudo Profile's ID) and the `issuer` of the ID (`sudoplatform.sudoservice` for Sudo Profile IDs).

## Errors

The `getEntitlementsConsumption` API will throw errors in the the following circumstances:

{% tabs %}
{% tab title="Swift" %}

|                        |                                                                                                                                                         |                                                                                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Exception**          | Condition                                                                                                                                               | Action                                                                                                                                          |
| `.notSignedIn`         | User was not signed in when `getEntitlements` was invoked.                                                                                              | Ensure user is signed in prior to invoking `getEntitlements`                                                                                    |
| `.invalidToken`        | The user's token does not contain a claim that can be mapped to an entitlements set, or the user has not been pre-configured with initial entitlements. | Ensure your identity provider has been set up to include an expected claim when federating sign-on or pre-configure the user with entitlements. |
| `.noEntitlementsError` | The user has not called `redeemEntitlements` yet and so their identity is not bound to any entitlements                                                 | Ensure `redeemEntitlements` has been called prior to attempting to retrieve entitlements consumption information                                |
| `.serviceError`        | A transient error occurred in the service while retrieving entitlements.                                                                                | Retry the request. If the problem persists, [ask us for help](https://sudoplatform.com/#lets-chat)                                              |
| {% endtab %}           |                                                                                                                                                         |                                                                                                                                                 |

{% tab title="Kotlin" %}
Errors in Kotlin are thrown as exceptions in the `SudoEntitlementsClient.EntitlementsException` class name space.

|                           |                                                                                                                                                     |                                                                                                                                                 |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Exception**             | Condition                                                                                                                                           | Action                                                                                                                                          |
| `NotSignedInException`    | User was not signed in when `getEntitlementsConsumption` was invoked.                                                                               | Ensure user is signed in prior to invoking `getEntitlementConsumption`                                                                          |
| `InvalidTokenException`   | The user's token does not contain a claim that can be mapped to an entitlements set, or has the user been pre-configured with initial entitlements. | Ensure your identity provider has been set up to include an expected claim when federating sign-on or pre-configure the user with entitlements. |
| `NoEntitlementsException` | The user has not called `redeemEntitlements` yet and so their identity is not bound to any entitlements                                             | Ensure `redeemEntitlements` has been called prior to attempting to retrieve entitlements consumption information                                |
| `UnknownException`        | A transient error occurred in the service while retrieving entitlements.                                                                            | Retry the request. If the problem persists, [ask us for help](https://sudoplatform.com/#lets-chat)                                              |
| {% endtab %}              |                                                                                                                                                     |                                                                                                                                                 |

{% tab title="JavaScript" %}

|                       |                                                                                                                                                     |                                                                                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Error**             | Condition                                                                                                                                           | Action                                                                                                                                          |
| `NotSignedInError`    | User was not signed in when `getEntitlements` was invoked.                                                                                          | Ensure user is signed in prior to invoking `getEntitlements`                                                                                    |
| `InvalidTokenError`   | The user's token does not contain a claim that can be mapped to an entitlements set, or has the user been pre-configured with initial entitlements. | Ensure your identity provider has been set up to include an expected claim when federating sign-on or pre-configure the user with entitlements. |
| `NoEntitlementsError` | The user has not called `redeemEntitlements` yet and so their identity is not bound to any entitlements                                             | Ensure `redeemEntitlements` has been called prior to attempting to retrieve entitlements consumption information                                |
| `ServiceError`        | A transient error occurred in the service while retrieving entitlements.                                                                            | Retry the request. If the problem persists, [ask us for help](https://sudoplatform.com/#lets-chat)                                              |
| {% endtab %}          |                                                                                                                                                     |                                                                                                                                                 |
| {% endtabs %}         |                                                                                                                                                     |                                                                                                                                                 |