Skip to main content
View as Markdown

Error Handling & Best Practices - Content Management

Error Handling & Best Practices​

Error Handling​

Error CodeMeaning
INVALID_USER_IDUser ID not found
USER_ALREADY_EXISTSA user with this ID already exists
USER_ROLE_NOT_FOUNDRole ID not found
INVALID_ROLE_IDRole ID is invalid
PROPERTY_VALIDATION_CANNOT_BE_NULLRequired filter property missing (e.g., groupUser.list needs groupIdEqual or userIdEqual)
LOGIN_DATA_NOT_FOUNDLogin credentials not found for user
PASSWORD_STRUCTURE_INVALIDPassword does not meet complexity requirements
ADMIN_LOGIN_USERS_QUOTA_EXCEEDEDMaximum admin users reached for the account
USER_LOGIN_ALREADY_ENABLEDLogin already enabled for this user
USER_LOGIN_ALREADY_DISABLEDLogin already disabled for this user
INVALID_FIELD_VALUEInvalid 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.
  • 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) 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 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.