Skip to main content
View as Markdown

Error Handling & Best Practices - Content Management

Error Handling & Best Practices​

Error Handling​

Error CodeMeaning
CAPTION_ASSET_ID_NOT_FOUNDCaption asset ID does not exist
ENTRY_ID_NOT_FOUNDEntry ID does not exist when creating caption asset
INVALID_ENTRY_IDInvalid entry ID format
CAPTION_ASSET_IS_NOT_READYCaption asset is not in READY status (cannot serve)
CAPTION_ASSET_ALREADY_EXISTSDuplicate caption for same entry/language/format
CAPTION_ASSET_FILE_NOT_FOUNDCaption content file not found
CAPTION_ASSET_INVALID_FORMATCaption file content does not match declared format
CAPTION_ASSET_PARSING_FAILEDCaption file parsing error (malformed SRT, invalid XML, etc.)
CAPTION_ASSET_PARAMS_ID_NOT_FOUNDCaption params template ID not found
CAPTION_ASSET_ENTRY_ID_NOT_FOUNDEntry referenced by caption does not exist
FLAVOR_ASSET_ID_NOT_FOUNDGeneric asset not found error

Retry strategy: For transient errors (HTTP 5xx, timeouts), retry with exponential backoff: 1s, 2s, 4s, with jitter, up to 3 retries. For client errors (ENTRY_ID_NOT_FOUND, CAPTION_ASSET_INVALID_FORMAT), fix the request before retrying. For CAPTION_ASSET_IS_NOT_READY, poll with captionAsset.get until status reaches READY (2).

Best Practices​

  • Two-step creation. Always create the asset first (captionAsset.add), then upload content (captionAsset.setContent). This ensures the asset metadata (language, format, label) is set before content processing begins.
  • Use KalturaStringResource for small captions. For files under ~1 MB, KalturaStringResource with inline content is simpler than the upload token flow. Use KalturaUploadedFileTokenResource for larger files.
  • Use getUrl + HTTP fetch for server-side consumption. serve returns a redirect to the CDN. getUrl returns a direct URL string — fetch it with a standard HTTP client.
  • Use serveWebVTT for player integration. Converts any source format to WebVTT on the fly. Use for HTML5 <track> elements and custom players.
  • Use serveAsJson for AI/LLM integrations. Returns structured timestamps in milliseconds — ideal for RAG, summarization, and programmatic analysis.
  • One default caption per entry. Use captionAsset.setAsDefault after uploading. The player auto-displays the default caption. Only one caption can be default per entry.
  • Set accuracy on machine-generated captions. The accuracy field enables automatic deduplication when human captions replace machine captions for the same language.
  • Use REACH for automated captioning; manual API for corrections/imports. REACH handles the transcription pipeline. Use the caption API to upload corrected files or import captions from external sources.
  • Use eSearch for caption text search. Use KalturaESearchCaptionItem for indexed full-text search across all entries at once. See eSearch API.
  • Caption every entry for accessibility compliance. Use REACH auto-rules to ensure all new entries get captioned. Run periodic audits (section 13.5) to catch gaps.
  • format is insertOnly. Choose the correct caption format at creation time — it remains fixed for the lifetime of the asset.
  • Use DFXP/TTML for multi-language single-file uploads. Upload a single DFXP file with language="Multilingual" and the server auto-splits into per-language assets.
  • Use Captions Studio for interactive editing. The Captions Studio (Captions Editor) provides a browser-based editor with synchronized video/waveform playback. Create a caption asset first, then pass its ID to the editor. See Captions Editor Guide for embed details.