커스텀몰 API / 오류·멱등 키
오류 코드·멱등 키
2xx가 아니면 본문에 오류 코드를 담아 주세요. 릴로는 코드를 보고 다음 행동을 정해요.
오류 형식
오류 응답
{
"error": {
"code": "not_allowed_in_state",
"message": "Shipped orders can't be canceled",
"order_status": "N30"
}
}오류 코드
| HTTP | code | 언제 | 릴로 동작 |
|---|---|---|---|
| 400 | invalid_request | 필수 값 없음, 형식 오류(우편번호 등) | 실패 → 담당자 확인 |
| 401 | unauthorized | 키 없음·틀림 | 실패, 콘솔에 연결 오류 |
| 403 | forbidden | 이 키에 쓰기 권한 없음 | 실패 → ‘쇼핑몰 권한 없음’ |
| 404 | not_found | 주문·쿠폰·회원 없음, 또는 소유자 불일치 | ‘찾을 수 없음’으로 처리 |
| 409 | not_allowed_in_state | 상태 규칙에 맞지 않음 | 실패 → 상태와 함께 담당자에게 |
| 409 | already_requested | 같은 품목에 취소·반품·교환이 이미 진행 중 | 고객에겐 ‘이미 접수됨’으로 안내 |
| 409 | idempotency_conflict | 같은 키, 다른 본문 | 실패 (릴로 쪽 문제 신호) |
| 409 | out_of_stock | 교환할 옵션이 품절 | 다른 옵션 안내 |
| 409 | coupon_unavailable | 기간 끝·발급 한도·이미 발급 | 실패 → 담당자 확인 |
| 429 | rate_limited | 호출 제한 | 실패 (자동 재시도 없음) |
| 5xx | internal | 장애 | 같은 키로 1번 재시도 후 실패 |
조회에서 429·5xx가 나면 오류로 기록하고, 고객에게는 확인한 뒤 다시 안내해요.
멱등 키
- 모든 쓰기에
Idempotency-Key헤더(최대 64자)가 붙어요. - 같은 키를 24시간 이상 기억해 주세요.
- 같은 키 + 같은 본문이면 다시 실행하지 말고 처음 응답(상태 코드·본문)을 그대로 돌려주세요.
- 같은 키 + 다른 본문이면 409
idempotency_conflict예요. - 릴로는 네트워크 오류·502·503·504일 때만 같은 키로 한 번 다시 보내요.
페이지 넘기기
- 기본은 커서예요. 응답의
meta.next_cursor를 다음 요청의cursor로 보내고, 마지막 페이지는null이에요. - 카페24식 offset만 되는 쇼핑몰은 capabilities에
"pagination": "offset"을 넣어 주세요. 릴로가offset·limit을 보내고, 받은 건수가limit보다 적으면 끝으로 봐요.offset은 최대 8000이에요. - 카탈로그 전체 목록은 페이지 방식과 상관없이
since_product_no를 써요.