상태 코드 및 오류 메시지

  • 카페24 API를 호출하는 과정에서 발생하는 오류 메시지 형식 및 코드를 정의합니다.
  • 기본적인 오류코드는 Http Response Code를 기반으로 확장하여 제공합니다.

API 오류 코드

  • 오류 코드는 기본적으로 Http Response Code 규칙을 확장한 개념으로 제공됩니다.
  • 기본 오류 코드 구조
기본 오류 코드 구조
Response Class 설명
2XX Success (성공)
4XX Client Error (클라이언트 오류)
5XX Server Error (서버 오류)
  • 4xx이 발생할 경우 요청 양식을 다시 확인해주시고, 5xx 에러가 지속적으로 발생할 경우 카페24 개발자센터로 문의해 주시기 바랍니다.

  • 기본 오류 코드 상세
기본 오류 코드 상세
Code 오류 메세지 Header 발생하는 케이스
200 Success OK GET 성공, PUT 성공, DELETE 성공시
201 Successfully created Created POST 성공시
207 Multi-status exists. Multi Status 다중 요청 등록시 상태가 개체별로 다른 경우
400 Content-type is not an application/json in the header. Bad Request 서버에서 요청을 이해할 수 없음.
1) Content-Type이 잘 못 지정되어있음
2) application/type이 json이 아님
400 Bad Request Bad Request 요청 API URL에 한글 또는 특수문자를 인코딩하지 않고 그대로 사용한 경우
401 Authority to access is not valid. Unauthorized 1) AccessToken 없이 호출한 경우
2) AccessToken이 유효하지 않은 경우
3) AccessToken이 만료된 경우
4) 알 수 없는 클라이언트일 경우
401 API cannot be used. Please enter the App key. Unauthorized Front API 사용시 client_id를 미입력한 경우
403 No authority to access Forbidden 1) AccessToken은 있으나 해당 Scope에 권한이 없음
2) Front API에서 볼 수 있는 권한이 없도록 설정됨
403 It is not the https protocol. Forbidden https 프로토콜이 아닌 경우
403 It is not a new product shopping mall. Forbidden 뉴상품 쇼핑몰이 아닌 경우
403 This app is deleted. Receive the consent of the operator again. Forbidden (Admin API 호출시) 쇼핑몰에서 해당 앱이 삭제된 경우
403 This app is not installed. Receive the consent of the operator again. Forbidden (Front API 호출시) 쇼핑몰에서 해당 앱이 삭제된 경우
403 Requested client_id is blocked. Forbidden 해당 client_id가 다음과 같은 이유로 차단된 경우
1) 특정 client_id가 리소스 서버의 부하를 일으킴
2) 해당 App이 앱스토어 가이드라인을 위반한 경우
404 No API found. Not Found 1) API URL을 잘못 호출한 경우에 모두 해당
2) 리소스를 찾을 수 없을 경우
404 The ID of the entity is not valid. Not Found {#id}가 없는 경우
422 An invalid request is entered. Unprocessable Entity 조회/처리 요청시 값이 정해진 스펙과 다를 경우
1) 필수 파라메터 누락함
2) 정해진 스펙과 다를 경우
429 Too much requests occur. Too many request 조회(GET) 요청시 정의되지 않은 파라메터를 입력함
500 A temporary server error occurs. Internal Server Error 내부 서버 에러, 알 수 없는 에러
503 You cannot use the service. Service Unavailable 현재 서버가 다운된 경우
503 The current API cannot be used. Service Unavailable 서버가 다운된 경우. API를 사용할 수 없음
504 Gateway time-out Gateway Timeout 요청 시간이 초과된 경우(Timeout)

주요 오류 해결 방법

  • 주요 오류 케이스에 대한 해결 가이드를 제공합니다.
  • 주요 오류 해결 방법
주요 오류 해결 방법
Status Code 오류메시지 오류 해결 방법
207 Multi-status exists. 오류 상태를 객체별로 확인하여 해당 상태에 따라 대응합니다.
400 Content-type is not an application/json in the header. 요청시 "Content-Type"이 application/json으로 되어있는지 확인합니다.
400 Bad Request 요청 API URL에 한글 또는 특수문자를 URL 인코딩하였는지 확인합니다.
401 Authority to access is not valid. 유효한 발급 절차에 따라 발급받은 AccessToken을 사용하였는지 확인합니다.
401 API cannot be used. Please enter the App key. 유효한 클라이언트 ID를 사용하였는지 확인합니다.
403 No authority to access API를 호출할 수 있는 권한이 있는지 API의 Scope 또는 쇼핑몰의 설정을 확인합니다.
403 It is not the https protocol. API 요청시 https 로 요청하였는지 확인합니다.
403 It is not a new product shopping mall. 쇼핑몰이 (뉴)상품관리로 업그레이드 되어야 사용 가능합니다.
403 This app is deleted. Receive the consent of the operator again. 쇼핑몰에 앱이 설치되었는지 확인 후 앱을 다시 설치합니다.
403 This app is not installed. Receive the consent of the operator again. 쇼핑몰에 앱이 설치되었는지 확인 후 앱을 다시 설치합니다.
403 Requested client_id is blocked. 개발자센터로 문의해주세요.
404 No API found. 엔드포인트 URL의 오류가 있는지 API 문서를 참고하여 확인합니다.
404 The ID of the entity is not valid. 요청한 엔드포인트의 Entity ID가 실제로 존재하는 값인지 확인합니다.
422 An invalid request is entered. API 문서를 참고하여 필수 파라메터가 입력되지 않았거나 유효하지 않은 값을 입력하였는지 확인합니다.
429 Too much requests occur. API 최대 허용 요청 건수를 초과하지 않도록 잠시 후 다시 요청합니다.
500 A temporary server error occurs. 일시적으로 에러가 발생하였습니다. 잠시 후에 다시 시도합니다.
503 You cannot use the service. 개발자센터로 문의해주세요.
503 The current API cannot be used. 개발자센터로 문의해주세요.
504 Gateway time-out 일시적으로 에러가 발생하여 응답이 지연되고 있습니다. 잠시 후에 다시 시도해주세요.

오류 메시지 구조

  • 오류 메시지의 구조는 3가지 형태(Request, Response, Biz logic)로 나뉘어져 제공됩니다.
  • 응답 메시지 기본 구조

HTTP/1.1 status
{
"리소스": [
{
"key": value,
"key": "value"

}
]
}

  • 오류 메시지 구조 : Request 사양 오류 샘플
설명 : Biz Logic 실행전 요청 파라미터에 대해 사양 체크시 에러가 발생된 경우에 해당됩니다.

HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": 4220,
"message": "이미지 타입 항목이 올바른 입력값이 아닙니다. (parameter.image_upload_type)"

}
}

  • 오류 메시지 구조 : Response 사양 오류 샘플
설명 : Biz Logic 실행후 응답 속성값에 대해 사양 체크시 에러가 발생된 경우에 해당됩니다.

HTTP/1.1 200 OK
{
"error": {
"code": 4003,
"message": "아이콘 리스트 항목이 배열 최대사이즈 5를 초과하였습니다. (properties.icon)"

}
}

  • 오류 메시지 구조 : Biz logic 실행 오류 샘플
설명 : Biz Logic 실행시 에러가 발생된 경우에 해당됩니다.

HTTP/1.1 500 Internal Server Error
{
"error": {
"code": "5002",
"message": "DB 입력 실패",
"more_info": {
"event_no": "1"
}

}
}

  • 오류 메시지 구조 : fail collection
설명 : 여러 개의 request에 대하여 오류가 발생한 경우에 해당됩니다.

HTTP/1.1 500 Internal Server Error
{
"errors": [
{
"code": "5002",
"message": "DB 입력 실패",
"more_info": {
"event_no": "1"
}

},
{
"code": "5002",
"message": "DB 입력 실패",
"more_info": {
"event_no": "2"
}

}
]
}

  • 오류 메시지 구조 : success&fail collection
설명 : 여러 개의 request에 대하여 성공과 오류가 동시에 발생한 경우에 해당됩니다.

HTTP/1.1 200 OK
{
"products": [
{
"event_no": "1",
"item_code": "TEST_123",
"item_value": "test"

}
],
"errors": [
{
"code": "5002",
"message": "Failed to insert database",
"more_info": {
"event_no": "2"
}

}
]
}

기타 참고사항

  • 정의된 오류코드 이외에 오류가 발생할 수 있는 상황에 대한 참고자료 입니다.
  1. SSL 인증서가 없는 상태에서 개인정보(private)와 관련된 영역에 접근하는 경우
    개인정보가 포함된 API 호출시 SSL만 접근허용 가능하기 때문에 호출 API의 개인정보 포함 여부에 따라 프토토콜을 지원합니다.
    - PUBLIC : 사이트접속한 프로토콜로 API 호출됨
    - PRIVATE : https로만 API 호출됨

    사용자가 접속한 프로토콜과 동일한 프로토콜로 API를 호출되어야 하며 문제를 사전에 방지하기 위해 상대경로를 이용할 것을 권장합니다.
    - 예시) https://{{domain}}/api/v2/products → /api/v2/products
  2. Front API를 위한 Javascript SDK 제공
    Front API만을 이용하여 개발된 App을 위하여 SSL 접근 및 상대경로 문제를 해결하기 위한 Front API Javascript SDK를 제공합니다.