트러블슈팅 & FAQ

API 연동 중 자주 발생하는 에러와 해결 방법, 자주 묻는 질문을 정리했습니다.

자주 발생하는 에러

아래 표에서 에러 상황별 원인과 해결 방법을 확인하세요.

에러	원인	해결 방법
`401 Unauthorized`	API Key가 잘못되었거나, 환경 URL이 맞지 않음	API Key 확인, `api-sandbox` vs `api` URL 확인
`402 Payment Required`	충전금 잔액 부족	`GET /credits/balance`로 잔액 확인, 파트너 포털에서 충전
`400 Validation Error`	필수 필드 누락 또는 잘못된 값	응답의 `fieldErrors` 배열에서 구체적인 필드 오류 확인
`404 Not Found`	잘못된 `bookUid` 또는 `orderUid`	생성 응답에서 받은 UID가 맞는지 확인
`429 Too Many Requests`	Rate Limit 초과	`Retry-After` 헤더 확인 후 대기, 요청 빈도 줄이기
이미지 업로드 실패	SVG 미지원, 파일 손상	JPG / PNG / WebP / HEIC 형식 사용
Finalization 실패	최소 페이지 수 미충족	콘텐츠 페이지를 추가하여 최소 페이지 요건 충족
Webhook 미수신	URL 접근 불가, HTTPS 미사용, 방화벽 차단	`POST /webhooks/test`로 수신 테스트, HTTPS URL 확인
주문 취소 실패	`PDF_READY` 이후 상태에서 취소 시도	파트너는 `PAID` / `PDF_READY` 상태에서만 취소 가능

401 Unauthorized 에러가 반환됩니다. Sandbox Key는 api-sandbox.sweetbook.com, Live Key는 api.sweetbook.com에서만 사용할 수 있습니다. URL이 올바른지 확인하세요.

Sandbox 환경에서는 테스트 가격이 적용됩니다. Live 환경의 실제 단가는 협의 후 API(GET /book-specs)로 조회할 수 있습니다.

파트너 포털에서 자유롭게 테스트 충전금을 추가할 수 있습니다. 테스트 충전금은 실제 돈이 아니므로 개발 및 테스트 기간 동안 부담 없이 사용하세요.

아니요. Sandbox와 Live 환경은 완전히 분리되어 있습니다. 도서, 주문, 충전금, 웹훅 설정 등 모든 데이터가 독립적으로 관리됩니다.

즉시 파트너 포털에서 해당 API Key를 폐기하고 새로운 Key를 재발급하세요. 노출된 Key로 발생한 피해는 복구가 어려울 수 있으므로 빠른 대응이 중요합니다.

주문이 발송되면 shipping.departed 웹훅이 발송됩니다. 페이로드에 포함된 tracking_number와 tracking_carrier를 사용하여 택배사 사이트에서 배송을 추적할 수 있습니다.

파트너 포털에서 불량 사진을 첨부하여 접수하세요. 접수 후 3~4 영업일 내에 재제작이 진행됩니다.