표준 에러 코드 및 JSON 규격

SmallPict API의 공식 에러 코드 매핑, 표준화된 JSON 에러 구조 및 HTTP 상태 코드 정리.

SmallPict의 모든 에러 응답은 정형화된 JSON 봉투(Envelope)에 담겨 반환되며, 기계가 쉽게 읽을 수 있는 강타입 에러 코드를 제공합니다.

표준 에러 JSON 구조

JSON

{  "error": {    "code": "QUOTA_EXCEEDED",    "message": "Monthly image processing quota limit reached for your plan.",    "details": {      "current_bytes": 10737418240,      "quota_bytes": 10737418240,      "reset_at": "2026-09-01T00:00:00Z"    }  }}

공식 에러 코드 종합 레퍼런스

HTTP 상태 코드	비즈니스 에러 코드 (Enum)	SDK 매핑 예외 클래스	에러 발생 상황 및 원인
400	`VALIDATION_FAILED`	`ValidationError`	요청 페이로드 검증 실패 또는 필수 필드 누락
400	`FILE_TOO_LARGE`	`FileTooLargeError`	단일 파일 크기가 현재 플랜 한도를 초과함
400	`UNSUPPORTED_FORMAT`	`UnsupportedFormatError`	지원하지 않는 이미지 파일 형식
401	`UNAUTHORIZED`	`AuthenticationError`	API 키, 타임스탬프 또는 HMAC 서명이 유효하지 않음
401	`ERR_TIMESTAMP_DRIFT`	`AuthenticationError`	클라이언트 시간이 허용 오차(±300초)를 벗어남
402	`QUOTA_EXCEEDED`	`QuotaExceededError`	당월 이미지 처리 쿼터가 모두 소진됨
402	`OVERAGE_EXCEEDED`	`QuotaExceededError`	플랜별 허용 초과 버퍼 한도 도달
403	`FORBIDDEN`	`PermissionDeniedError`	폐기된 키이거나 계정이 일시 정지됨
403	`KEY_SCOPE_MISMATCH`	`ScopeMismatchError`	호출한 API와 API 키의 권한 스코프 불일치
404	`NOT_FOUND`	`NotFoundError`	요청한 변환 작업 ID(`job_id`) 또는 리소스 없음
429	`RATE_LIMIT_EXCEEDED`	`RateLimitError`	단시간 내 과도한 요청 발생 (`Retry-After` 준수 필요)
500	`INTERNAL_ERROR`	`ServerError`	서버 내부에서 처리되지 않은 예외 발생
502	`CDN_UPSTREAM_ERROR`	`CdnError`	SmallPict Edge CDN 캐시 퍼지 또는 동기화 오류

SDK 자동 예외 처리 및 복원력

공식 SmallPict SDK는 이러한 JSON 에러를 각 프로그래밍 언어의 네이티브 예외 객체로 자동 래핑하며, 일시적인 429 및 5xx 에러 수신 시 지터가 포함된 지수 백오프로 자동 재시도합니다.