Error Handling & Best Practices - Content Management

Error Handling & Best Practices

Error Handling

Error Code	Meaning
CATEGORY_NOT_FOUND	Category ID does not exist
DUPLICATE_CATEGORY	A category with this name already exists under the same parent
PARENT_CATEGORY_NOT_FOUND	The specified parentId does not exist
MAX_CATEGORY_DEPTH_REACHED	Category hierarchy depth limit exceeded
CANNOT_DELETE_OR_UPDATE_TOP_CATEGORY	Cannot modify the root category
CATEGORY_USER_ALREADY_EXISTS	User is already a member of this category
INVALID_ENTRY_ID	Entry ID does not exist
ENTRY_CATEGORY_ALREADY_EXISTS	Entry is already assigned to this category
CATEGORY_ENTRY_NOT_FOUND	The entry is not assigned to this category
MAX_CATEGORIES_FOR_ENTRY_REACHED	Entry already assigned to 32 categories (default limit)
INVALID_USER_ID	User ID does not exist

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, CATEGORY_NOT_FOUND, INVALID_ENTRY_ID), fix the request before retrying.

Best Practices

• Design hierarchy before creating categories. Plan your category tree structure in advance. Moving categories later triggers a full path recalculation for all descendants.
• Use referenceId for external system mapping. Store external system IDs in referenceId to simplify integration and avoid needing to track Kaltura category IDs.
• Delete children before parents. When cleaning up category trees, delete child categories first. Deleting a parent cascades to children, but explicit ordering gives you more control.
• Use privacyContext to segment entitlement. Assign different privacyContext labels to different category trees so you can enable entitlement for specific contexts without affecting others.
• Use categoryUser for fine-grained permissions. Permission levels (MANAGER, MODERATOR, CONTRIBUTOR, MEMBER) provide granular control over what each user can do within a category.
• Prefer enableentitlement in USER KS. ADMIN KS has entitlement disabled by default. For production playback, generate USER KS (type=0) with enableentitlement and the appropriate privacycontext.
• 32 categories per entry limit. An entry can be assigned to a maximum of 32 categories. Accounts with FEATURE_DISABLE_CATEGORY_LIMIT get 1000. Plan your category hierarchy accordingly.
• Least-restrictive wins. When an entry is in multiple categories, the least restrictive privacy setting determines access. Design your category assignments with this in mind.
• Use contributionPolicy=2 with moderation=1 for moderated categories. This ensures only authorized users can suggest content, and moderators approve additions.
• Use userJoinPolicy to control membership. AUTO_JOIN for open categories, REQUEST_TO_JOIN for moderated membership, NOT_ALLOWED for invitation-only.