# 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 %}         |                                                                                                                                                     |                                                                                                                                                 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sudoplatform.com/guides/entitlements/end-user-api/retrieving-entitlements.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.