Error Handling & Best Practices - Content Management

Error Handling & Best Practices

Error Handling

Error Code	Meaning	Resolution
UPLOAD_TOKEN_NOT_FOUND	Token ID does not exist or expired	Create a new token
UPLOAD_PASSED_MAX_RESUME_TIME_ALLOWED	Partial upload expired (7-day limit)	Create a new token and re-upload
MAX_ALLOWED_CHUNK_COUNT_EXCEEDED	Too many chunks uploaded	Use larger chunk sizes
UPLOAD_TOKEN_CANNOT_MATCH_EXPECTED_SIZE	Final chunk doesn't match expected total	Retry the final chunk
UPLOAD_TOKEN_FILE_TYPE_RESTRICTED	File type not allowed	Check account file type restrictions
UPLOADED_FILE_NOT_FOUND_BY_TOKEN	Upload not yet completed	Complete the upload before calling addContent
ENTRY_ID_NOT_FOUND	Entry ID does not exist	Verify the entry ID; may have been deleted
INVALID_ENTRY_TYPE	Operation not supported for this entry type	Use the correct service for the entry type
MAX_FILE_SIZE_EXCEEDED	File exceeds the partner's upload limit	Use chunked upload or request limit increase
Import stuck at status 0	URL resource points to a redirect or manifest	Use a direct file URL with KalturaUrlResource, not a streaming manifest or redirect URL

Retry strategy: For transient errors (HTTP 5xx, timeouts), retry with exponential backoff: 1s, 2s, 4s, with jitter, up to 3 retries. For client errors (UPLOAD_TOKEN_NOT_FOUND, ENTRY_ID_NOT_FOUND), fix the request before retrying. For async operations (transcoding, URL imports), poll with increasing intervals (5s, 10s, 30s).

Best Practices

• Use chunked upload for files > 10 MB. Chunked upload supports resume on failure via resumeAt. Use autoFinalize=1 with fileSize to simplify the protocol.
• Use media.addContent with KalturaUrlResource for remote files. Provide direct file URLs — redirect URLs (playManifest, HLS) cause import failures. The two-step pattern (media.add + media.addContent) gives explicit control over entry metadata before triggering ingestion.
• Use the correct resource type for each ingestion pattern: KalturaUploadedFileTokenResource for local uploads, KalturaUrlResource for URL imports, KalturaEntryResource for copying content, KalturaOperationResource for clipping, KalturaAssetsParamsResourceContainers for multi-flavor ingest.
• Use baseEntry.clone for entry duplication. Clone provides a full deep copy (metadata, flavors, captions, cue points) with granular control over what to include. Use KalturaEntryResource only when you need a new entry with independent metadata.
• Use KalturaOperationResource for clips. Create time-based clips by specifying offset (ms) and duration (ms). Source must be a READY entry. For multi-clip concatenation, use KalturaOperationResources (plural).
• Poll for READY status after upload. Check media.get for status=2 before performing operations that require processed content.
• Use referenceId for cross-system linking. Set a reference ID matching your CMS's content ID, then use baseEntry.listByReferenceId to look up entries.
• Use updateContent for version management. Replace the source file while preserving the entry ID, embed codes, and analytics history.
• Use Access Control profiles to restrict content delivery by IP, domain, geo, or scheduling.
• Use AppTokens for upload services. Scope the AppToken with edit:* privilege for upload-only access. See AppTokens Guide.
• Set up Agents Manager or REACH rules to auto-process uploaded content (captions, translation, summarization) rather than manual post-upload workflows.
• 10,000 result limit on list/search. Use createdAtGreaterThanOrEqual date-window filters to page through results beyond 10K.
• Use multirequest for browser uploads. Combine uploadToken.add + media.add + media.addContent in a single HTTP request. See Multirequest.
• Content-Type auto-detection. Kaltura detects MIME types during upload. You do not need to specify Content-Type headers for uploaded files.