에러 처리

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

에러 응답 형식

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

HTTP 상태 코드

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

에러 코드

코드	상태	설명
`VALIDATION_ERROR`	400	요청 본문 또는 쿼리 유효성 검사 실패
`INVALID_CURRENCY`	400	스토어 통화와 불일치
`MISSING_API_KEY`	401	Authorization 헤더 누락
`INVALID_API_KEY`	401	API 키가 유효하지 않거나 만료됨
`INVALID_CUSTOMER_TOKEN`	401	고객 JWT 토큰이 유효하지 않음
`RESOURCE_NOT_FOUND`	404	요청한 리소스를 찾을 수 없음
`INSUFFICIENT_STOCK`	409	요청 수량에 대한 재고 부족
`INVALID_STATE_TRANSITION`	409	허용되지 않는 주문 상태 전환
`CART_NOT_ACTIVE`	409	장바구니가 이미 완료되었거나 만료됨
`DISCOUNT_EXPIRED`	409	할인 코드가 만료되었거나 사용 한도 초과
`RATE_LIMIT_EXCEEDED`	429	현재 윈도우에서 요청 과다
`INTERNAL_ERROR`	500	예상치 못한 서버 오류

에러 처리 예시

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
}