핵심 개념 · 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	중복 데이터 (이벗WMS 전용)
`RATE_LIMIT_EXCEEDED`	429	요청 한도 초과 (Rate Limits)
`INTERNAL_ERROR`	500	서버 내부 오류 — 운영팀 문의

WMS · 매니저 도메인 에러

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

이벗캠 에러

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

페이똑딱 에러

페이똑딱은 도메인 전용 에러 코드가 없습니다. 위의 인증 에러 · 공통 에러만 사용합니다.

조회 결과가 없을 때는 404 가 아닙니다 조건에 맞는 입금 내역이 없으면 HTTP 200 + 빈 배열 ("data": []) 이 반환됩니다. data.length 로 판단하세요. 또한 페이똑딱은 JWT 전용이므로 X-API-Key 로만 호출하면 403 AUTH_FORBIDDEN 이 반환됩니다 — 인증 가이드 참고.

부분 실패 (행 단위)

일괄 등록 endpoint 는 전체가 모두 성공하거나 모두 실패하는 방식이 아니라, 행 단위로 성공/실패가 갈리는 "부분 실패" 응답을 사용합니다. 현재 이벗WMS 전용이며, 한 번에 최대 1,000건까지 보낼 수 있습니다.

POST /v3/wms/orders/draft
HTTP 200
{
  "success": true,
  "data": {
    "created_count": 8,
    "failed_count": 2,
    "drafts": [
      {
        "mall_order_no": "20260614-000001",
        "mall_product_name": "유기농 사과 5kg",
        "draft_id": "10231",
        "status": "open",
        "created_at": "2026-06-14 11:17:23",
        "success": true,
        "result_message": ""
      },
      {
        "mall_order_no": "20260614-000003",
        "mall_product_name": "유기농 배 3kg",
        "draft_id": "",
        "status": "open",
        "created_at": "",
        "success": false,
        "result_message": "등록에 실패했습니다."
      }
    ]
  }
}

성공·실패가 별도 배열로 나뉘지 않습니다. 요청한 순서 그대로 한 배열에 담겨 오며, 각 행의 success (boolean) 와 result_message 로 판별하십시오. 건수 필드와 결과 배열의 이름은 endpoint 마다 다릅니다.

endpoint	건수 필드	결과 배열
`POST /v3/wms/orders`	`created_count` · `failed_count`	`results`
`POST /v3/wms/orders/draft`	`created_count` · `failed_count`	`drafts`
`POST /v3/wms/products/{product_code}/options`	`added_count` · `failed_count`	`options`

주의 — HTTP 200 이어도 실패가 섞일 수 있습니다 success: true 라도 반드시 failed_count 와 각 행의 success 를 확인하셔야 합니다. 단, 요청 본문의 형식 오류(필수 항목 누락 등)는 행 단위로 처리되지 않습니다 — 한 행이라도 형식이 어긋나면 요청 전체가 400 으로 거부되며 아무것도 등록되지 않습니다. 부분 실패는 형식 검증을 통과한 뒤 DB 저장 단계에서만 발생합니다.

트러블슈팅

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 가이드 의 모범 사례(백오프·배치·캐싱·비동기 큐)를 적용하세요.

429 는 게이트웨이의 초당 속도 제한과 인증키의 월 호출 한도 두 곳에서 발생합니다. 응답 본문은 둘 다 동일한 RATE_LIMIT_EXCEEDED 이지만, 게이트웨이 쪽에는 Retry-After 헤더가 붙지 않습니다. Retry-After 유무로 구분하세요 — 없으면 속도 제한(백오프 후 재시도), 있으면 월 한도 소진(재시도로 해결되지 않음)입니다.

500 — 서버 내부 오류

재현 가능한 요청 본문 + 호출한 전체 URL(query string 포함) + 요청 시각(분 단위 정확히)을 모아 help@ebut.co.kr 로 보내주시면 빠르게 분석해드립니다.