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

## Error Handling & Best Practices

### Error Handling


| Error | Meaning | Resolution |
|-------|---------|------------|
| `ENTRY_ID_NOT_FOUND` | Entry does not exist | Verify entry ID |
| `ENTRY_DELETED_MODERATED` | Entry was deleted or rejected | Entry no longer available |
| `THUMB_ASSET_ID_NOT_FOUND` | Thumb asset does not exist | Verify thumb asset ID |
| `THUMB_ASSET_IS_DEFAULT` | Attempted to delete the current default thumb asset | Set a different thumb as default first, then delete |
| `TOO_MANY_PROCESSES` | Server at concurrent ImageMagick process limit | Transient — retry after a brief delay |
| `FILE_DOES_NOT_EXIST_ON_CURRENT_DC` | Source file on a different data center | Request is auto-redirected; retry follows redirect |
| Blank/placeholder image | Entry not yet READY or no source for frame capture | Wait for entry to reach READY status |
| `FEATURE_BLOCK_THUMBNAIL_CAPTURE` | Frame capture blocked by access control | Entry has `LIMIT_THUMBNAIL_CAPTURE` rule |




### Best Practices


- **Use the dynamic thumbnail URL for display.** The URL API serves images at any size with CDN caching — stored thumb assets are for editorial purposes (custom uploads, saved captures).  
- **Use `type=3` (center crop) for uniform grids.** It guarantees exact dimensions while keeping the most important part of the image (center).  
- **Use `type=2` (resize with padding) for mixed aspect ratios.** It preserves the full image within fixed dimensions, padding with `bgcolor`.  
- **Use sprite strips for timeline scrubbers.** A single `/vid_slices/20/width/160/height/90` request creates a 3200×90 sprite. Parse in CSS with `background-position`.  
- **Use `nearest_aspect_ratio=1` for multi-thumbnail entries.** If an entry has both landscape and portrait thumb assets, this parameter automatically selects the one that best matches the requested dimensions.  
- **Set `vid_sec` for consistent thumbnails.** Specifying a timestamp (e.g., `/vid_sec/5`) ensures every entry in a gallery uses the same relative frame position, producing a uniform visual grid.  
- **Use short-lived URLs for access-controlled content.** Thumbnail URLs with `/ks/\{KS\}` are cached per KS value. Use KS with appropriate expiry to prevent stale access.  
- **Keep sprite dimensions within pixel limits.** Ensure `width × vid_slices < 65,500` and `height × vid_slices < 65,500`.  
- **Upload custom thumbnails for editorial control.** For featured content, upload purpose-designed thumbnails via `thumbAsset.addFromImage` to ensure the ideal visual representation.  
- **Use thumbParams for automation.** Associate thumbnail templates with conversion profiles so every upload automatically gets correctly-sized thumbnails.