Snapkit Logo

제한사항 및 에러 처리#

시스템 제한사항을 이해하고 효과적으로 에러를 처리하는 방법을 배워보세요.

시스템 제한사항#

처리 제한#

제한 유형값설명
최대 이미지 크기16384 x 16384 픽셀출력 이미지의 최대 크기
입력 픽셀 제한268,402,689 픽셀약 16K x 16K
파일 크기 제한50MB최대 입력 파일 크기
처리 타임아웃60초최대 처리 시간
블러 강도0-20CPU 보호 제한
DPR 범위1.0-4.0Device pixel ratio 제한

포맷별 제한사항#

포맷최대 크기비고
WebP16383 x 16383더 큰 이미지는 PNG 또는 JPEG 사용
AVIF, PNG, JPEG시스템 제한특정 포맷 제한 없음

응답 헤더#

기본 응답 헤더#

모든 이미지 변환 요청은 다음 헤더를 포함합니다:

헤더설명예시
Content-Type이미지의 MIME 타입

image/webp, image/jpeg

Content-Disposition파일명 정보 (RFC 5987 준수)inline; filename="image.webp"
Cache-Control캐싱 정책 (1년)public, max-age=31536000, immutable

변환 실패 헤더#

이미지 변환이 실패하면, 원본 이미지가 다음 추가 헤더와 함께 반환됩니다:

헤더설명예시
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

응답 헤더 확인#

JavaScript/TypeScript 예시

const response = await fetch(imageUrl);
 
// 변환 실패 확인
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(`변환 실패: ${reason}`);
  console.log(`메시지: ${message}`);
  console.log(`제안: ${suggestion}`);
}

에러 카테고리#

주요 에러 카테고리와 해결 방법:

  • image-too-large-for-format: 포맷 크기 제한 초과 → PNG 또는 JPEG 사용
  • file-size-exceeded: 파일 크기 50MB 초과 → 이미지 압축 또는 해상도 감소
  • corrupted-image: 손상되거나 불완전한 이미지 → 유효한 이미지로 재업로드
  • invalid-parameters: 잘못된 변환 파라미터 → 유효한 범위로 조정
  • processing-timeout: 처리 타임아웃 (60초) → 이미지 크기 축소 또는 변환 옵션 단순화

자동 폴백 시스템#

시스템이 자동으로 변환 실패를 처리합니다:

  1. 파라미터 에러: 잘못된 값 자동 수정 또는 무시
  2. 변환 실패: 원본 이미지 반환 + 에러 헤더
  3. 메모리 부족: 처리 제한으로 시스템 안정성 보장
  4. 포맷 에러: 원본 포맷 유지 또는 안전한 포맷으로 폴백

일반적인 문제 해결#

WebP 크기 제한 초과#

# 문제: X-Snapkit-Reason: image-too-large-for-format
 
# 해결 1: PNG 또는 JPEG 사용
?transform=w:800,format:png
 
# 해결 2: 이미지 크기 축소
?transform=w:400,h:300,format:webp

파라미터 범위 에러#

# 문제: X-Snapkit-Reason: invalid-parameters
 
# 해결: 유효한 범위로 수정
?transform=w:800,quality:85  # quality는 1-100

Best Practices#

  1. format:auto 사용 - 자동 포맷 선택
  2. 적절한 DPR 설정 - 기기 유형에 따라 (2.0 데스크탑, 3.0 모바일)
  3. 응답 헤더 모니터링 - 변환 실패 감지
  4. 폴백 로직 구현 - 변환 실패 시 대응
  5. 제한 내에서 유지 - 안정적인 처리 보장

다음 단계#