# 오류 코드 목록

오류 응답의 `error.code`는 안정적입니다. 문구가 아니라 코드로 분기하세요. `error.docUrl`은 여기 해당 행을 가리킵니다.

| 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `AUTH_MISSING_TOKEN` | 인증 토큰 누락 | Authorization 헤더에 `Bearer <token>` 을 보내세요(/api/v1 에서는 ?token= 을 받지 않음). 토큰은 POST /api/v1/auth/token 에 client_id + client_secret 을 본문으로 보내 받습니다. |
| `AUTH_INVALID_TOKEN` | 유효하지 않은 토큰 | 토큰 형식 또는 서명이 잘못되었습니다. POST /api/v1/auth/token 으로 새로 받고, 잘리거나 공백이 섞이지 않았는지 확인하세요. |
| `AUTH_EXPIRED` | 토큰 만료 | 토큰 유효기간이 지났습니다. 새로 발급받으세요. 만료 직전 자동 갱신을 권장합니다. |
| `SCOPE_DENIED` | 권한 없는 작업 | 채널 역할에 이 기능이 포함되어 있지 않습니다. "이용 플랜"에서 플랜을 신청하세요. 담당자 승인 즉시 적용됩니다. |
| `WAREHOUSE_DENIED` | 권한 없는 창고 | 해당 창고 허용 목록에 채널이 없습니다. 담당자에게 창고 추가를 요청하거나, 목록을 비우면 전체 허용됩니다. |
| `AUTHZ_UNAVAILABLE` | 인가 서비스 일시 중단 | 권한 서비스가 일시적으로 응답하지 않습니다. 잠시 후 다시 시도하고, 계속되면 requestId 와 함께 담당자에게 문의하세요. |
| `VALIDATION_FAILED` | 잘못된 요청 파라미터 | error.param 에 표시된 필드를 수정하세요. 엔드포인트별 상세 규격은 /swagger 에 있습니다. |
| `NOT_FOUND` | 항목을 찾을 수 없음 | 품번 / SKU / 전표번호가 존재하지 않거나 철자가 틀렸습니다. 확인 후 다시 시도하세요. |
| `OWNERSHIP_DENIED` | 해당 전표에 대한 권한 없음 | 이 전표는 다른 채널 소유입니다. 본인 채널의 주문 / 출고 / 홀드만 조회할 수 있습니다. |
| `UPSTREAM_ERROR` | 상위 ERP 오류 | 상위 ERP 에 일시적 장애가 있습니다. 잠시 후 재시도하고, requestId 를 알려주시면 해당 호출을 추적할 수 있습니다. |
| `UPSTREAM_TIMEOUT` | 상위 시스템 응답 시간 초과 | 상위 ERP 응답이 느리거나 연결되지 않습니다. 잠시 후 재시도하세요. |
| `INTERNAL` | 게이트웨이 내부 오류 | 게이트웨이 자체 오류입니다(드묾). requestId 와 함께 문의하세요. |
| `ADMIN_UNAUTHORIZED` | 관리자 토큰 불일치 | x-admin-token 이 서버 .env 의 ADMIN_TOKEN 과 일치하는지 확인하세요. |
| `ADMIN_DISABLED` | 관리자 콘솔 비활성화 | 서버에 ADMIN_TOKEN 이 설정되지 않았습니다. 설정 후 재시작하세요. |
| `IDEMPOTENCY_IN_PROGRESS` | 동일한 요청이 처리 중 | 같은 Idempotency-Key 를 사용한 이전 요청이 아직 끝나지 않았습니다. 같은 key 로 잠시 후 재시도하세요. key 를 바꾸면 중복 생성 위험이 있습니다. |
| `IDEMPOTENCY_MISMATCH` | Idempotency-Key 재사용 | 이 key 는 내용이 다른 요청에 이미 사용되었습니다. 업무 건별로 새 key(UUID 또는 자체 주문번호)를 사용하세요. |
| `IDEMPOTENCY_INVALID_KEY` | 유효하지 않은 Idempotency-Key | key 는 최대 255자입니다. UUID 사용을 권장합니다. |
| `RATE_LIMITED` | 호출 한도 초과 | RateLimit-Remaining / Retry-After 응답 헤더를 확인하고 잠시 후 재시도하세요. 전체 재고 조회는 비쌀니다(1회 60점). 증분 조회 /Changes?since= 는 1점만 사용합니다. 한도가 부족하면 담당자에게 상향을 요청하세요. |
| `BAD_REQUEST` | 잘못된 요청 | HTTP 메서드, 경로, 요청 본문을 확인하세요. |
| `READ_ONLY_MODE` | 읽기 전용 환경 | 이 서버는 안전한 테스트를 위해 상위 ERP 쓰기를 의도적으로 비활성화했습니다(WRITES_ENABLED=0). 조회는 정상 작동합니다. 실제 주문은 운영 환경을 사용하세요. |
| `ENDPOINT_GONE` | 엔드포인트 종료 | API 가 /api/v1/** 로 이동했습니다(소문자 경로, snake_case 파라미터). error.message 에 대체 주소가 있으며 전체 목록은 /reference 또는 /llms.txt 에 있습니다. |
| `WAREHOUSE_UNKNOWN` | 알 수 없는 창고 | GET /api/v1/warehouses 에 나열된 코드(AU / AUSYD2 / AUSYD1 / CN / CHNZJ1)를 쓰세요. AuStock 같은 별칭은 더 이상 없습니다. |
| `UPSTREAM_REJECTED` | ERP 가 요청을 거부함 | ERP 가 이 요청을 받아들이지 않았습니다(재고 부족, 없는 번호, 잘못된 필드 등). 이유는 error.message 에 있습니다. 수정 후 재시도하고, 반복되면 request_id 를 담당자에게 보내세요. |
| `AUTH_BAD_CREDENTIALS` | 자격 증명 오류 | 채널 방식: client_id 와 client_secret 을 확인하세요(시크릿은 발급 시 한 번만 표시되며 분실 시 관리자에게 재발급 요청). OMS 계정 방식(grant_type=password): OMS 웹사이트 로그인 계정과 비밀번호를 확인하세요. 체험은 sandbox / sandbox. |
| `AUTH_LOCKED` | 로그인 실패 횟수 초과 — 일시 잠금 | 같은 OMS 계정으로 비밀번호를 연속 틀리면 15분간 잠깁니다. 계정과 비밀번호를 확인한 뒤 다시 시도하세요. 체험은 sandbox / sandbox. |
| `DUPLICATE_SUSPECTED` | 중복 의심 대행 건 | 동일 수령인 + 동일 SKU 를 짧은 시간에 다시 제출하면 업스트림이 중복으로 판단합니다. 의도한 것이라면 client_order_number 를 바꾸거나 잠시 후 다시 시도하세요. |
| `OMS_LOGIN_REQUIRED` | OMS 계정 로그인이 필요한 엔드포인트 | POST /api/v1/auth/token 에 grant_type=password 와 OMS 계정으로 토큰을 받으세요(채널 시크릿 토큰은 배정 규칙이 OMS 계정을 따르므로 주문 흐름을 쓸 수 없습니다). |
| `SHIPPING_REQUIRED` | 배송 정보 누락 | 도매 주문에는 배송 방식이 필요합니다: GET /api/v1/shipping-methods 에서 shipping_method_id 를 골라 shipping 에 넣고, 배송이면 GET /api/v1/addresses 에서 address_id 도 고르세요. OMS 사이트의 사용자 → 환경설정에서 기본값을 지정할 수도 있습니다. |

## 오류 응답

```json
{
  "error": {
    "code": "WAREHOUSE_DENIED",
    "message": "권한 없는 창고",
    "hint": "…",
    "request_id": "r_8f2c1a",
    "doc_url": "https://connect.everugg.net.au/errors/WAREHOUSE_DENIED"
  }
}
```

HTTP 상태 코드가 유일한 성공 신호입니다. `error.code` 는 안정적이고 `message` 와 `hint` 는 `Accept-Language` 를 따릅니다.

---
Markdown 원본: https://connect.everugg.net.au/reference/errors.md?lang=ko · 웹 페이지: https://connect.everugg.net.au/reference?sec=errors&lang=ko