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

## Error Handling & Best Practices

### Error Handling


| Error Code | Meaning | Resolution |
|------------|---------|------------|
| `FEATURE_FORBIDDEN` | Account lacks `FEATURE_ENTRY_REPLACEMENT` | Required for trim/updateContent operations (one-time setup by your Kaltura account team) |
| `ENTRY_REPLACEMENT_ALREADY_EXISTS` | Entry already has a pending replacement | Wait for current replacement to complete or fail, then retry |
| `ENTRY_ID_NOT_FOUND` | Source entry does not exist | Verify the entry ID is correct and not deleted |
| `FLAVOR_ASSET_ID_NOT_FOUND` | Specified flavor does not exist on the source entry | Omit `flavorParamsId` to use the default source, or verify available flavors via `flavorAsset.list` with `entryIdEqual` |
| `INVALID_ENTRY_STATUS` | Source entry is not in READY status | Wait for source entry processing to complete (status=2) |
| `ENTRY_REPLACEMENT_FAILED` (replacementStatus=4) | Processing of the replacement content failed | Check source content validity; retry the operation |
| `MAX_CLIP_COUNT_EXCEEDED` | Too many clips in concatenation | Default limit is 5 clips; reduce segment count or request limit increase |
| `MAX_DURATION_EXCEEDED` | Concatenated output exceeds maximum | Default limit is 5 hours total; shorten segments |

**Retry strategy:** For `ENTRY_REPLACEMENT_ALREADY_EXISTS`, poll `baseEntry.get` until `replacementStatus` returns to `0` (NONE), then retry. For transient HTTP errors, use exponential backoff (1s, 2s, 4s) with up to 3 retries.




### Best Practices


- **Use `baseEntry.clone` + `media.updateContent` for clips.** This preserves the source entry's metadata on the clip and creates a clean separation between the original and the extracted segment.  
- **Use `media.updateContent` for trim (in-place).** This preserves entry ID, embed codes, analytics history, and all associated metadata. Always complete the replacement flow with `media.approveReplace`.  
- **Verify source entries are READY (status=2) before editing.** All operation resources require fully transcoded source content. Poll `media.get` if the source was recently uploaded.  
- **Omit `flavorParamsId` for maximum quality.** When omitted, the system uses the entry's source flavor. Specify a `flavorParamsId` only when you need a particular transcoded rendition as the editing source. Use `flavorAsset.list` with `entryIdEqual` to discover available flavors.  
- **Set clip duration explicitly.** Always specify both `offset` and `duration` in milliseconds. Omitting duration results in undefined behavior.  
- **Use complementary audio volume model intentionally.** Setting overlay volume to 0.7 means main video drops to 0.3 — plan audio levels accordingly.  
- **Use `desiredLines` for waveform resampling.** Match the number of data points to your UI's pixel width for efficient rendering.  
- **Process one replacement at a time per entry.** The API enforces single-replacement locking. Queue sequential edits and wait for each to complete.  
- **Use dimension normalization for multi-source concat.** When splicing sources with different resolutions, set `dimensionsAttributes` to avoid unexpected output dimensions.  
- **Use `KalturaAspectRatioScaleAttributes` over crop when preserving content matters.** Crop removes pixels; scale adds black bars but preserves the full frame.  
- **Burn captions for social distribution.** Use `KalturaRenderCaptionAttributes` when distributing to platforms that strip subtitle tracks (Instagram, TikTok-style sharing).  
- **Use ASS color format correctly.** Colors are `&HBBGGRR&` (reversed from RGB). White is `&H00FFFFFF&`, not `#FFFFFF`.