---
title: Error Handling & Best Practices
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/user-management-reference
---

## Error Handling & Best Practices

### Error Handling


| Error Code | Meaning |
|------------|---------|
| `INVALID_USER_ID` | User ID not found |
| `USER_ALREADY_EXISTS` | A user with this ID already exists |
| `USER_ROLE_NOT_FOUND` | Role ID not found |
| `INVALID_ROLE_ID` | Role ID is invalid |
| `PROPERTY_VALIDATION_CANNOT_BE_NULL` | Required filter property missing (e.g., groupUser.list needs groupIdEqual or userIdEqual) |
| `LOGIN_DATA_NOT_FOUND` | Login credentials not found for user |
| `PASSWORD_STRUCTURE_INVALID` | Password does not meet complexity requirements |
| `ADMIN_LOGIN_USERS_QUOTA_EXCEEDED` | Maximum admin users reached for the account |
| `USER_LOGIN_ALREADY_ENABLED` | Login already enabled for this user |
| `USER_LOGIN_ALREADY_DISABLED` | Login already disabled for this user |
| `INVALID_FIELD_VALUE` | Invalid value for a field (e.g., invalid email format) |

**Retry strategy:** For transient errors (HTTP 5xx, timeouts), retry with exponential backoff: 1s, 2s, 4s, with jitter, up to 3 retries. For client errors (HTTP 400, `INVALID_USER_ID`, `USER_ALREADY_EXISTS`), fix the request before retrying.




### Best Practices


- **Use meaningful user IDs.** Email addresses work well as user IDs — they're unique, recognizable, and match the pattern used by AuthBroker SSO provisioning.
- **Use AppTokens for production auth.** Generate KS via `appToken.startSession` with HMAC — keep admin secrets off application servers. See [AppTokens API](/docs/getting-started/authentication/app-tokens-overview).
- **Scope roles with least privilege.** Create custom roles with only the permissions needed. Start from `BASE_USER_SESSION_PERMISSION` and add specific permissions. Use `userRole.clone` to customize built-in roles without modifying originals.
- **Prefer `setrole` over `isAdmin`.** Instead of making users admin, create a scoped role and use `setrole:ROLE_ID` in KS privileges (see [Session Guide](/docs/getting-started/authentication/ks-overview)) to limit what a session can do.
- **Clean up user profiles before deleting users.** Deleting a KalturaUser cascades to all User Profiles. If you need to preserve profile data or control the order, delete profiles first via the User Profile API.
- **Use groups for batch operations.** Create groups and use them as recipients in Messaging and notification targets in [Webhooks](/docs/rich-media-cms-apis/integration/webhooks) rather than managing individual user lists.
- **Use `groupUser.sync` for SSO group management.** When integrating with an IdP that provides group claims, use sync to keep Kaltura groups in lockstep with the IdP rather than manual add/delete.