Skip to main content
View as Markdown

Error Handling & Best Practices - Content Management

Error Handling & Best Practices​

Error Handling​

Error CodeMeaningResolution
FEATURE_FORBIDDENAccount lacks FEATURE_ENTRY_REPLACEMENTRequired for trim/updateContent operations (one-time setup by your Kaltura account team)
ENTRY_REPLACEMENT_ALREADY_EXISTSEntry already has a pending replacementWait for current replacement to complete or fail, then retry
ENTRY_ID_NOT_FOUNDSource entry does not existVerify the entry ID is correct and not deleted
FLAVOR_ASSET_ID_NOT_FOUNDSpecified flavor does not exist on the source entryOmit flavorParamsId to use the default source, or verify available flavors via flavorAsset.list with entryIdEqual
INVALID_ENTRY_STATUSSource entry is not in READY statusWait for source entry processing to complete (status=2)
ENTRY_REPLACEMENT_FAILED (replacementStatus=4)Processing of the replacement content failedCheck source content validity; retry the operation
MAX_CLIP_COUNT_EXCEEDEDToo many clips in concatenationDefault limit is 5 clips; reduce segment count or request limit increase
MAX_DURATION_EXCEEDEDConcatenated output exceeds maximumDefault 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.