오류 코드

예스24 Open API에서 반환하는 공통 오류 코드 목록입니다.

모든 오류 응답은 아래 공통 JSON 구조로 반환됩니다.

{ "success": false, "errorCode": "AUTH_001", "message": "오류 메시지", "data": null }

인증 오류 (AUTH)

코드	HTTP	메시지	원인 및 해결
`AUTH_001`	401	X-Api-Key 헤더가 없습니다.	요청에 `X-Api-Key: {apiKey}` 헤더를 추가하세요.
`AUTH_002`	401	유효하지 않은 API Key입니다.	Key 값이 올바른지 확인하세요. 폐기된 키 또는 비활성 계정의 키는 인증이 거부됩니다.

코드	HTTP	메시지	원인 및 해결
`RATE_001`	429	초당 호출 허용량을 초과했습니다. 잠시 후 다시 시도해주세요.	초당 호출 한도를 초과했습니다. 잠시 후 다시 시도하세요.
`RATE_002`	429	일일 호출 허용량을 초과했습니다.	Key별 일일 호출 한도를 초과했습니다. 한도는 매일 자정에 초기화됩니다. 현재 사용량은 API 이용 현황에서 확인할 수 있습니다.

코드	HTTP	메시지	원인 및 해결
`PARAM_007`	400	Invalid request parameter.	요청 경로 또는 쿼리스트링이 허용 범위를 초과하거나 유효하지 않은 문자가 포함되어 있습니다.

코드	HTTP	메시지 (예시)	원인 및 해결
`PARAM_001`	400	categoryId 파라미터를 입력하세요.	필수 파라미터(categoryId)가 누락됐습니다. API 문서의 Required 항목을 확인하세요.
`PARAM_002`	400	date 파라미터는 yyyy-MM-dd 형식이어야 합니다.	날짜 파라미터의 형식이 잘못됐습니다. `yyyy-MM-dd` 형식으로 입력하세요. (예: `2026-06-01`)
`PARAM_003`	400	query 파라미터를 입력하세요.	필수 파라미터(query)가 누락됐습니다. 검색어를 입력하세요.
`PARAM_004`	400	유효하지 않은 query 입니다.	파라미터 값 형식이 잘못됐습니다. ItemId는 숫자, ISBN13은 13자리 숫자인지 확인하세요.
`PARAM_005`	400	유효하지 않은 sort 값입니다.	허용되지 않는 정렬 값입니다. 각 API 문서에서 허용 가능한 `sort` 값을 확인하세요.
`PARAM_006`	400	유효성 검사 실패	요청 모델의 유효성 검사에 실패했습니다. 파라미터 타입과 값 범위를 확인하세요.

코드	HTTP	메시지	원인 및 해결
`CATEGORY_001`	404	카테고리 결과가 없습니다.	요청한 카테고리 ID에 해당하는 결과가 없습니다. 유효한 카테고리 ID인지 확인하세요.
`BEST_001`	404	베스트셀러 결과가 없습니다.	실시간/종합/특가/스테디셀러/일별/월별 베스트셀러 조회 시 결과가 없는 경우입니다. 카테고리 ID 또는 날짜 범위를 확인하세요.
`NEW_001`	404	신상품 결과가 없습니다.	해당 카테고리의 신상품 목록이 없습니다.
`ATTN_001`	404	주목할 신상품 결과가 없습니다.	해당 카테고리의 주목 신상품 목록이 없습니다.

코드	HTTP	메시지	원인 및 해결
`SEARCH_001`	404	검색 결과가 없습니다.	검색어에 해당하는 상품이 없습니다. 다른 키워드로 검색하세요.
`GOODS_001`	404	상품 상세 정보가 없습니다. 상품 목차 정보가 없습니다.	요청한 상품 ID에 해당하는 상품이 없거나 목차 정보가 제공되지 않습니다.
`GOODS_002`	404	ISBN13에 해당하는 상품을 찾을 수 없습니다.	`searchType=ISBN13`으로 조회 시 해당 ISBN이 존재하지 않습니다. ISBN13 값(13자리 숫자)이 정확한지 확인하세요.
`AUTHOR_404`	404	작가 정보가 없습니다.	요청한 상품의 작가 정보가 제공되지 않습니다.

코드	HTTP	메시지	원인 및 해결
`INTERNAL_ERROR`	500	서버 내부 오류가 발생했습니다.	서버 내부 오류입니다. 잠시 후 재시도하세요. 지속될 경우 발생 API, 요청 파라미터, 발생 시각을 1:1 문의로 알려 주세요.
`UPSTREAM_UNAVAILABLE`	503	외부 서비스가 일시적으로 사용할 수 없습니다. 잠시 후 다시 시도해주세요.	외부 연동 서비스 장애입니다. 잠시 후 재시도하세요. 지속될 경우 공지사항을 확인하세요.