API Status Code 가이드
카페24 API는 표준 HTTP 상태 코드를 사용하여 API 요청의 결과를 나타냅니다. 각 상태 코드의 의미와 대응 방법을 아래에서 확인하세요.
✅ 성공 응답 (2xx)
200 OK
GET, PUT, DELETE 요청이 정상적으로 처리되었음을 나타냅니다.
발생 사례:
- GET 조회 요청 성공
- PUT 수정 요청 성공
- DELETE 삭제 요청 성공
예제:
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products' \\
-H 'Authorization: Bearer {access_token}' \\
-H 'Content-Type: application/json'
응답 예제:
{
"resource": {
"product_no": 128,
"product_name": "Sample Product",
"price": 10000
}
}
201 Created
POST 요청으로 새로운 리소스가 성공적으로 생성되었음을 나타냅니다.
발생 사례:
- 상품 등록
- 주문 생성
- 카테고리 추가
예제:
curl -X POST 'https://{mallid}.cafe24api.com/api/v2/admin/products' \\
-H 'Authorization: Bearer {access_token}' \\
-H 'Content-Type: application/json' \\
-d '{
"product_name": "New Product",
"price": 15000
}'
207 Multi-Status
다중 요청 처리 시 객체별로 상태가 다를 경우 반환됩니다.
발생 사례:
- 여러 상품 동시 등록 시 일부만 성공
- 배치 업데이트 중 부분 실패
오류 해결 방법: 각 객체별 상태 코드를 확인하고 해당 상태에 따라 대응하세요.
응답 예제:
{
"resource": [
{
"product_no": 101,
"status": 201,
"message": "Created successfully"
},
{
"product_no": 102,
"status": 400,
"message": "Invalid parameter"
}
]
}
❌ 클라이언트 오류 (4xx)
400 Bad Request
서버가 요청을 이해할 수 없는 경우입니다.
발생 사례:
-
Content-Type 오류
- Content-Type이 잘못 지정된 경우
- application/type이 json이 아닌 경우
-
인코딩 오류
- API URL에 한글 또는 특수문자를 인코딩하지 않은 경우
오류 해결 방법:
# ❌ 잘못된 예
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/products?name=상품'
# ✅ 올바른 예
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/products?name=%EC%83%81%ED%92%88'
확인 항목:
Content-Type: application/json헤더 확인- URL 파라미터 인코딩 확인
401 Unauthorized
인증 정보가 없거나 유효하지 않은 경우입니다.
발생 사례:
-
Access Token 미제공
- Authorization 헤더 없음
-
Access Token 유효하지 않음
- 잘못된 토큰
- 만료된 토큰
- 알 수 없는 클라이언트
-
Front API 사용 시
- client_id 미입력
오류 해결 방법:
Admin API:
# ✅ 올바른 인증 방식
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products' \\
-H 'Authorization: Bearer {access_token}' \\
-H 'Content-Type: application/json'
Front API:
# ✅ Front API는 client_id 사용
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/products' \\
-H 'X-Cafe24-Client-Id: {client_id}' \\
-H 'Content-Type: application/json'
확인 항목:
- 유효한 Access Token 발급 여부
- Token 만료 시간 확인
- 올바른 인증 방식 사용 (Admin API vs Front API)
403 Forbidden
인증은 되었으나 해당 리소스에 접근할 권한이 없는 경우입니다.
발생 사례:
-
Scope 권한 부족
- Access Token은 있으나 해당 Scope에 권한 없음
-
HTTPS 미사용
- HTTP로 요청한 경우
-
뉴상품 쇼핑몰 미업그레이드
- 구 상품관리 시스템 사용 중
-
앱 삭제
- 쇼핑몰에서 앱이 삭제된 경우
오류 해결 방법:
- API 권한 확인
# Scope 권한이 필요한 경우 새로운 토큰 발급
# 개발자센터에서 앱 권한 설정 확인
- HTTPS 사용
# ❌ 잘못된 예
curl -X GET 'http://{mallid}.cafe24api.com/api/v2/admin/products'
# ✅ 올바른 예
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products'
- 앱 재설치
- 쇼핑몰에서 앱이 삭제된 경우 다시 설치
404 Not Found
요청한 리소스를 찾을 수 없는 경우입니다.
발생 사례:
-
잘못된 URL
- 엔드포인트 오류
- 리소스 경로 오류
-
리소스 미존재
- 존재하지 않는 상품 번호
- 존재하지 않는 주문 번호
-
ID 누락
{#id}값이 없는 경우
오류 해결 방법:
# API 문서에서 올바른 엔드포인트 확인
# 예: GET /api/v2/admin/products/{product_no}
# ❌ 잘못된 예
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/prodcuts' # typo
# ✅ 올바른 예
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products/128'
409 Conflict
동일한 리소스에 동일한 내용으로 중복 업데이트하려는 경우입니다.
발생 사례:
- 변경된 데이터 없이 PUT 요청
오류 해결 방법:
# 수정할 데이터를 요청해주세요
# 변경사항이 있는 데이터만 전송하도록 수정
422 Unprocessable Entity
요청 데이터가 스펙과 다르거나 유효하지 않은 경우입니다.
발생 사례:
-
필수 파라미터 누락
- 필수 필드 비워 둔 경우
-
유효하지 않은 값
- 잘못된 데이터 타입
- 범위 초과 값
- 정해진 스펙에 맞지 않는 값
오류 해결 방법:
# API 문서의 필수 파라미터 확인
curl -X POST 'https://{mallid}.cafe24api.com/api/v2/admin/products' \\
-H 'Authorization: Bearer {access_token}' \\
-H 'Content-Type: application/json' \\
-d '{
"product_name": "Sample Product", # 필수
"price": 10000, # 필수
"supply_price": 5000, # 필수
"category_no": 1 # 필수
}'
확인 항목:
- 필수 파라미터 포함 여부
- 데이터 타입 일치 여부
- 값의 유효성 검증
429 Too Many Requests
API 요청이 Rate Limit을 초과한 경우입니다.
발생 사례:
- Bucket 초과 (순간적인 과도한 요청)
- API 최대 허용 요청 건수 초과
Rate Limit 정책:
Admin API (Leaky Bucket):
- Bucket이 쇼핑몰당 설정된 호출건 수 제한만큼 찬다
- Bucket은 1초에 2회씩 감소
- 1초에 2회 이하 호출 시 제약 없음
D.Collection API:
- IP당 1분에 최대 40회
오류 해결 방법:
# Rate Limit 헤더 확인
# X-Api-Call-Limit 확인하여 요청 조절
# 예: X-Api-Call-Limit: 1/40
# 해결책: 잠시 후 다시 요청
# 또는 요청 속도 조절
모범 사례:
// 예제: Node.js에서 Rate Limit 처리
const makeRequest = async (url) => {
try {
const response = await fetch(url, {
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
}
});
// Rate Limit 헤더 확인
const remaining = response.headers.get('X-Api-Call-Limit');
if (!remaining) {
// Rate limit 도달, 재시도 필요
await delay(1000);
return makeRequest(url);
}
return response.json();
} catch (error) {
console.error('API Error:', error);
}
};
🔴 서버 오류 (5xx)
500 Internal Server Error
서버 내부 오류가 발생한 경우입니다.
발생 사례:
- 알 수 없는 서버 에러
- 일시적인 에러
오류 해결 방법:
- 잠시 후 다시 시도해주세요
- 계속 발생하면 개발자센터로 문의
503 Service Unavailable
서버가 현재 다운되었거나 사용할 수 없는 경우입니다.
발생 사례:
- 서버 점검
- 서버 다운
오류 해결 방법:
- API를 사용할 수 없음
- 서버 복구 대기
- 개발자센터로 문의
504 Gateway Timeout
요청 처리 시간이 초과된 경우입니다.
발생 사례:
- 응답 시간 초과
- 일시적인 네트워크 지연
오류 해결 방법:
# 잠시 후 다시 시도해주세요
# 지속적인 Timeout 발생 시 요청 구조 재검토
📊 에러 응답 형식
모든 API 오류는 다음 형식의 JSON으로 반환됩니다:
{
"error": {
"code": "error_code",
"message": "error message",
"more_info": {
// 추가 정보
}
}
}
🔗 관련 헤더
Rate Limit 관련 헤더
| 헤더 | 설명 |
|---|---|
X-Api-Call-Limit | 현재 API 호출 상태 (현재/제한) |
X-Cafe24-Call-Usage | 호출 횟수 한도 대비 사용률(%) |
X-Cafe24-Call-Remain | 호출 재개 가능까지 남은 시간(초) |
X-Cafe24-Time-Usage | 처리 시간 한도 대비 사용률(%) |
X-Cafe24-Time-Remain | 처리 시간 재개 가능까지 남은 시간(초) |
Cafe24 Analytics API 헤더
| 헤더 | 설명 |
|---|---|
X-RateLimit-Remaining | 남은 Token 수 |
X-RateLimit-Requested-Tokens | 요청 Token 수 |
X-RateLimit-Burst-Capacity | 최대 Bucket 용량 |
X-RateLimit-Replenish-Rate | 초당 Token 재증가 수 |
💡 Best Practices
1. 요청 전 확인 사항
- ✅ Authorization 헤더 확인
- ✅ Content-Type: application/json 확인
- ✅ HTTPS 사용 확인
- ✅ URL 파라미터 인코딩 확인
- ✅ 필수 파라미터 포함 확인
2. 에러 처리 전략
// 재시도 로직 (Exponential Backoff)
const retryWithBackoff = async (fn, maxRetries = 3) => {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
if (error.status === 429 || error.status >= 500) {
const delay = Math.pow(2, i) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
} else {
throw error;
}
}
}
};
3. Rate Limit 관리
- Response 헤더의 Rate Limit 정보 모니터링
- 요청 속도 조절
- Batch 요청 시 분산 처리