오류

HIOBuy는 두 가지 오류 형태를 사용합니다. 프로토콜 오류(2xx가 아닌 HTTP와 error 객체)와 비즈니스 결과(일부 주문 라우트에서 HTTP 200과 success: false)입니다.

프로토콜 오류(HTTP 4xx / 5xx) {#protocol-errors}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "product_id, url, mi_id, or tao_password is required.",
    "request_id": "req_abc123",
    "category": "VALIDATION_ERROR"
  }
}

필드	설명
`error.code`	머신이 읽을 수 있는 enum — 분기 로직에 사용
`error.message`	사람이 읽을 수 있는 설명(영어)
`error.request_id`	`x-request-id` 응답 헤더와 동일
`error.category`	큰 분류: `AUTH_ERROR`, `RATE_LIMIT_ERROR`, `VALIDATION_ERROR`, `CHANNEL_ERROR`, `INTERNAL_ERROR`
`error.upstream`	`CHANNEL_UPSTREAM_ERROR`에서 선택적으로 제공되는 벤더 오류 요약(정제됨)

오류 코드 참조 {#error-codes}

정식 머신 판독 카탈로그는 data/errors.catalog.json입니다. 요약은 다음과 같습니다.

코드	HTTP	분류	발생 시점
`INVALID_API_KEY`	401	AUTH_ERROR	Bearer 토큰이 없거나 유효하지 않음
`CHANNEL_NOT_AUTHORIZED`	401	AUTH_ERROR	이 앱에 채널이 인증되지 않음
`INSUFFICIENT_SCOPE`	403	AUTH_ERROR	이 키/앱에 작업이 허용되지 않음
`FULFILLMENT_MODE_NOT_SUPPORTED`	403	AUTH_ERROR	self-fulfillment 앱에서 `/v1/fulfillment/*` 호출
`VALIDATION_ERROR`	400	VALIDATION_ERROR	본문 필드 누락/오류, 지원하지 않는 `currency`
`UNSUPPORTED_CHANNEL`	400	VALIDATION_ERROR	알 수 없는 `channel` 값
`UNSUPPORTED_FIELD`	400	VALIDATION_ERROR	예: 상품 라우트의 `currency`
`NOT_FOUND`	404	VALIDATION_ERROR	주문 또는 리소스가 존재하지 않음
`RATE_LIMIT_EXCEEDED`	429	RATE_LIMIT_ERROR	분당 속도 제한 초과
`QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	일일 채널 쿼터 소진
`PLATFORM_QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	플랫폼 전체 용량 한도
`CHANNEL_CAPABILITY_NOT_SUPPORTED`	400	CHANNEL_ERROR	이 채널에서 사용할 수 없는 작업
`CHANNEL_UPSTREAM_ERROR`	502	CHANNEL_ERROR	마켓플레이스가 호출을 거부함
`INTERNAL_ERROR`	500	INTERNAL_ERROR	예기치 않은 Gateway 실패 — 백오프로 재시도
`PARCEL_NOT_FOUND`	404	VALIDATION_ERROR	유효하지 않거나 아직 입고되지 않은 소포(풀필먼트)
`INVALID_SHIPPING_CHANNEL`	400	VALIDATION_ERROR	잘못된 `shipping_channel_code`
`INSUFFICIENT_BALANCE`	402	VALIDATION_ERROR	결제하기에 풀필먼트 지갑 잔액이 부족함

비즈니스 실패(HTTP 200) {#business-failures}

구매 preview/create/pay는 Gateway 요청 자체가 유효하더라도 마켓플레이스가 작업을 거부하면 HTTP 200과 success: false를 반환할 수 있습니다.

{
  "channel": "1688",
  "success": false,
  "code": "ORDER_CREATE_FAILED",
  "message": "One or more lines could not be purchased.",
  "failed_offers": [
    {
      "offer_id": "...",
      "spec_id": "...",
      "error_code": "STOCK_NOT_ENOUGH",
      "error_message": "Insufficient stock"
    }
  ],
  "request_id": "req_..."
}

호출이 완료된 것으로 처리하기 전에 success를 확인하세요.
unavailable_lines(preview) 또는 failed_offers(create)를 확인하세요.
부분 성공: 1688은 success: true이면서 failed_offers가 비어 있지 않을 수 있습니다.

상품 upstream 실패 {#upstream-product-errors}

잘못된 Taobao口令, 없는 상품, 상품 라우트의 벤더 타임아웃은 보통 빈 상품 셸이 아니라 502와 CHANNEL_UPSTREAM_ERROR를 반환합니다.

권장 처리 방식 {#handling}

모든 오류 경로에서 request_id를 기록합니다.
429와 500은 지수 백오프로 재시도하고, 400 / 401은 입력을 수정하기 전에는 재시도하지 마세요.
502 CHANNEL_UPSTREAM_ERROR에서는 운영팀에 벤더 메시지를 노출하고, 일시적 장애라면 선택적으로 한 번 재시도합니다.
주문 생성: 멱등성을 위해 external_order_id / Taobao outer_purchase_id를 사용하세요 — Procurement orders 참고.