Error Handling & Best Practices - Content Management

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.