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

## Error Handling & Best Practices

### Error Handling


| Error Code | Meaning |
|------------|---------|
| `CAPTION_ASSET_ID_NOT_FOUND` | Caption asset ID does not exist |
| `ENTRY_ID_NOT_FOUND` | Entry ID does not exist when creating caption asset |
| `INVALID_ENTRY_ID` | Invalid entry ID format |
| `CAPTION_ASSET_IS_NOT_READY` | Caption asset is not in READY status (cannot serve) |
| `CAPTION_ASSET_ALREADY_EXISTS` | Duplicate caption for same entry/language/format |
| `CAPTION_ASSET_FILE_NOT_FOUND` | Caption content file not found |
| `CAPTION_ASSET_INVALID_FORMAT` | Caption file content does not match declared format |
| `CAPTION_ASSET_PARSING_FAILED` | Caption file parsing error (malformed SRT, invalid XML, etc.) |
| `CAPTION_ASSET_PARAMS_ID_NOT_FOUND` | Caption params template ID not found |
| `CAPTION_ASSET_ENTRY_ID_NOT_FOUND` | Entry referenced by caption does not exist |
| `FLAVOR_ASSET_ID_NOT_FOUND` | Generic 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](/docs/rich-media-cms-apis/content-management/esearch-overview).
- **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.