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

## 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](/docs/getting-started/authentication/app-tokens-overview).  
- **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](/docs/getting-started/general/api-multirequest).  
- **Content-Type auto-detection.** Kaltura detects MIME types during upload. You do not need to specify Content-Type headers for uploaded files.