메인 콘텐츠로 건너뛰기

​
에러 처리

API는 표준 HTTP 상태 코드를 사용하며 구조화된 JSON 에러 응답을 반환합니다.

​
에러 응답 형식

{
  "error": {
    "type": "invalid_request",
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "field": "email",
      "message": "Invalid email format"
    }
  }
}

​
HTTP 상태 코드

상태유형의미
400invalid_request잘못된 요청 — 유효하지 않은 파라미터 또는 본문
401authentication_errorAPI 키 누락 또는 유효하지 않음
403permission_error권한 부족 (예: Admin 라우트에 Publishable Key 사용)
404not_found리소스가 존재하지 않음
409conflict상태 충돌 (예: 재고 부족, 유효하지 않은 상태 전환)
429rate_limit요청 과다 — Rate Limit 초과
500server_error예상치 못한 서버 오류

​
에러 코드

코드상태설명
VALIDATION_ERROR400요청 본문 또는 쿼리 유효성 검사 실패
INVALID_CURRENCY400스토어 통화와 불일치
MISSING_API_KEY401Authorization 헤더 누락
INVALID_API_KEY401API 키가 유효하지 않거나 만료됨
INVALID_CUSTOMER_TOKEN401고객 JWT 토큰이 유효하지 않음
RESOURCE_NOT_FOUND404요청한 리소스를 찾을 수 없음
INSUFFICIENT_STOCK409요청 수량에 대한 재고 부족
INVALID_STATE_TRANSITION409허용되지 않는 주문 상태 전환
CART_NOT_ACTIVE409장바구니가 이미 완료되었거나 만료됨
DISCOUNT_EXPIRED409할인 코드가 만료되었거나 사용 한도 초과
RATE_LIMIT_EXCEEDED429현재 윈도우에서 요청 과다
INTERNAL_ERROR500예상치 못한 서버 오류

​
에러 처리 예시

const res = await fetch('/v1/storefront/products/prod_nonexistent', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!res.ok) {
  const { error } = await res.json();
  console.error(`[${error.code}] ${error.message}`);
  // [RESOURCE_NOT_FOUND] Product with id 'prod_nonexistent' not found
}