핵심 개념 · Error Codes

에러 코드

이벗 API v3 의 모든 에러는 일관된 구조로 반환됩니다. success: false + error.code + error.message 조합으로 클라이언트에서 안전하게 분기 처리할 수 있습니다.

공통 에러 응답

HTTP 400 | 401 | 403 | 404 | 409 | 429 | 500
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "사람이 읽을 수 있는 에러 메시지"
  }
}

왜 HTTP status 와 별도로 code 가 있나요? HTTP status 만으로는 같은 400 안에서도 "필수 누락"과 "값 형식 오류"를 구분할 수 없습니다. error.code 로 정확히 분기하고, error.message 는 사용자 안내용으로 활용하세요.

인증 에러

code	HTTP	설명
`AUTH_MISSING_TOKEN`	401	인증 헤더 누락
`AUTH_INVALID_TOKEN`	401	키/토큰 유효하지 않음
`AUTH_EXPIRED_TOKEN`	401	JWT 만료 — refresh 필요
`AUTH_FORBIDDEN`	403	접근 권한 부족

상세 처리 방법은 인증 가이드 를 참고하세요.

공통 에러

code	HTTP	설명
`INVALID_PARAMETER`	400	파라미터 형식 / 값 오류
`REQUIRED_PARAMETER`	400	필수 파라미터 누락
`NOT_FOUND`	404	리소스 없음
`DUPLICATE`	409	중복 데이터
`RATE_LIMIT_EXCEEDED`	429	요청 한도 초과 (Rate Limits)
`INTERNAL_ERROR`	500	서버 내부 오류 — 운영팀 문의

WMS · 매니저 도메인 에러

code	HTTP	설명
`ORDER_NOT_FOUND`	404	주문 없음
`ORDER_ALREADY_SHIPPED`	409	이미 출고된 주문 — 수정 불가
`ORDER_DRAFT_NOT_FOUND`	404	임시(오픈DB) 주문 없음
`INVENTORY_INSUFFICIENT`	400	재고 부족
`RETURN_CANCEL_EXPIRED`	400	반품 철회 가능 시간(18시) 초과
`PRODUCT_NOT_FOUND`	404	상품 없음
`OPTION_NOT_FOUND`	404	옵션 없음

이벗캠 에러

code	HTTP	설명
`CAM_INVOICE_NOT_FOUND`	404	해당 송장번호로 영상 없음

페이똑딱 에러

code	HTTP	설명
`PAY_DEPOSIT_NOT_FOUND`	404	입금 내역 없음
`PAY_ALREADY_PROCESSED`	409	이미 처리된 입금

부분 실패 (행 단위)

일괄 등록 endpoint (예: POST /orders/draft) 는 전체가 모두 성공하거나 모두 실패하는 방식이 아니라, 행 단위로 성공/실패가 갈리는 "부분 실패" 응답을 사용합니다.

HTTP 200
{
  "success": true,
  "data": {
    "succeeded_count": 8,
    "failed_count": 2,
    "succeeded": [
      { "row": 1, "order_no": "20260614-000001" },
      { "row": 2, "order_no": "20260614-000002" }
    ],
    "failed": [
      {
        "row": 3,
        "error": {
          "code": "PRODUCT_NOT_FOUND",
          "message": "상품 코드 'X123' 을 찾을 수 없습니다."
        }
      }
    ]
  }
}

주의 — HTTP 200 이어도 실패가 섞일 수 있습니다 일괄 등록 endpoint 는 success: true 라도 반드시 failed_count / failed[] 를 확인하셔야 합니다. 행 단위로 재처리 로직이 필요한 경우가 많습니다.

트러블슈팅

401 이 반복됩니다

키 / 토큰 헤더가 정확한지 (오타·공백·따옴표 포함 여부)
X-API-Key 와 Authorization 중 맞는 헤더를 쓰고 있는지
JWT 만료 여부 — AUTH_EXPIRED_TOKEN 이면 refresh 후 재시도

400 + REQUIRED_PARAMETER

endpoint 문서에서 필수 파라미터(required: true) 확인
GET 은 query string, POST 는 body 안에 위치하는지
대소문자 / snake_case 표기가 맞는지

429 가 자주 발생합니다

Rate Limits 가이드 의 모범 사례(백오프·배치·캐싱·비동기 큐)를 적용하세요.

500 — 서버 내부 오류

재현 가능한 요청 본문 + 요청 시각(분 단위 정확히) + X-Request-Id 헤더 값을 모아 help@ebut.co.kr 로 보내주시면 빠르게 분석해드립니다.