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

## 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.