> ## Documentation Index
> Fetch the complete documentation index at: https://docs.headlesscommerce.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 에러 처리

> API 에러 코드와 처리 방법

# 에러 처리

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

## 에러 응답 형식

```json theme={null}
{
  "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 | 예상치 못한 서버 오류 |

## 에러 처리 예시

```typescript theme={null}
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
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.