Limitations & Error Handling#

Understand system limitations and how to handle errors effectively.

System Limits#

Processing Limits#

Limit Type	Value	Description
Maximum image size	16384 x 16384 pixels	Maximum dimensions for output images
Input pixel limit	268,402,689 pixels	Approximately 16K x 16K
File size limit	50MB	Maximum input file size
Processing timeout	60 seconds	Maximum processing time
Blur intensity	0-20	CPU protection limit
DPR range	1.0-4.0	Device pixel ratio limits

Format-Specific Limits#

Format	Maximum Size	Notes
WebP	16383 x 16383	Use PNG or JPEG for larger images
AVIF	System limit	No specific format limit
PNG	System limit	No specific format limit
JPEG	System limit	No specific format limit

Response Headers#

Basic Response Headers#

All image transformation requests include the following headers:

Header	Description	Example
`Content-Type`	MIME type of the image	`image/webp`, `image/jpeg`
`Content-Disposition`	Filename information (RFC 5987 compliant)	`inline; filename="image.webp"`
`Cache-Control`	Caching policy (1 year)	`public, max-age=31536000, immutable`

Transform Failure Headers#

When image transformation fails, the original image is returned with these additional headers:

Header	Description	Example
`X-Snapkit-Transform-Failed`	Transform failure indicator	`true`
`X-Snapkit-Reason`	Failure category (see below)	`image-too-large-for-format`
`X-Snapkit-Message`	Detailed error message	`Processed image is too large for the WebP format`
`X-Snapkit-Suggestion`	Resolution suggestion	`Use PNG or JPEG format instead`

Checking Response Headers#

JavaScript/TypeScript Example

const response = await fetch(imageUrl);
 
// Check if transformation failed
const isFailed = response.headers.get('X-Snapkit-Transform-Failed') === 'true';
 
if (isFailed) {
  const reason = response.headers.get('X-Snapkit-Reason');
  const message = response.headers.get('X-Snapkit-Message');
  const suggestion = response.headers.get('X-Snapkit-Suggestion');
 
  console.log(`Transform failed: ${reason}`);
  console.log(`Message: ${message}`);
  console.log(`Suggestion: ${suggestion}`);
}

curl Command Example

curl -I "https://your-org-cdn.snapkit.studio/project/image.jpg?transform=w:20000,format:webp"
 
# Response example:
# X-Snapkit-Transform-Failed: true
# X-Snapkit-Reason: image-too-large-for-format
# X-Snapkit-Message: Processed image is too large for the WebP format
# X-Snapkit-Suggestion: Use PNG or JPEG format instead, or reduce image dimensions

Error Categories#

Category	Conditions	Resolution
`image-too-large-for-format`	Exceeds format size limits (WebP: 16383x16383, Input: 268M pixels)	Use PNG or JPEG format, or reduce image size
`file-size-exceeded`	File size exceeds 50MB	Compress image or reduce resolution
`corrupted-image`	Corrupted or incomplete image file	Verify file integrity and re-upload valid image
`unsupported-format`	Unsupported image format	Use JPEG, PNG, WebP, AVIF, GIF, or TIFF format
`invalid-parameters`	Invalid transform parameters (negative size, out of range, etc.)	Adjust parameters to valid ranges
`memory-limit-exceeded`	Insufficient memory for extremely large images	Reduce image size or resolution
`processing-timeout`	Processing timeout (60 seconds)	Reduce image size or simplify transform options
`format-conversion-failed`	Error during format conversion	Try different output format or check source image
`transform-failed`	Unexpected transformation error	Retry or contact support if issue persists

Auto Fallback System#

The system automatically handles transformation failures:

Parameter errors: Automatically correct or ignore invalid values
Transform failures: Return original image + error headers
Memory shortage: Ensure system stability with processing limits
Format errors: Preserve original format or fallback to safe format

Common Troubleshooting#

WebP Size Limit Exceeded#

# Issue: X-Snapkit-Reason: image-too-large-for-format
# Message: Processed image is too large for the WebP format
 
# Solution 1: Use PNG or JPEG
?transform=w:800,format:png
 
# Solution 2: Reduce image size
?transform=w:400,h:300,format:webp

Parameter Range Error#

# Issue: X-Snapkit-Reason: invalid-parameters
# Message: Expected integer between 1 and 100 for quality
 
# Solution: Correct to valid range
?transform=w:800,quality:85  # quality must be 1-100

Corrupted Image#

# Issue: X-Snapkit-Reason: corrupted-image
# Message: The image file is corrupted or incomplete
 
# Solution: Re-upload valid image file

Memory Limit#

# Issue: X-Snapkit-Reason: memory-limit-exceeded
# Message: Image too large to process
 
# Solution: Reduce dimensions
?transform=w:2000,h:2000,fit:inside

Memory Optimization#

Cache disabled: Sharp memory cache not used
Auto cleanup: Automatic release of Sharp library instances after processing completion
Single processing: Concurrency limited for memory protection

Best Practices#

Use format:auto for automatic format selection
Set appropriate DPR based on device type (2.0 for desktop, 3.0 for mobile)
Monitor response headers to detect transformation failures
Implement fallback logic when transforms fail
Stay within limits to ensure reliable processing

Next Steps#

Best Practices - Learn optimization strategies
Use Cases - See real-world examples