홈▸개발문서▸Error Codes

에러 코드 레퍼런스

SweetBook API에서 반환하는 HTTP 상태 코드와 에러 응답 형식을 안내합니다.

HTTP 상태 코드

SweetBook API는 다음 HTTP 상태 코드를 사용합니다.

코드설명비고
200성공요청이 정상적으로 처리됨
201리소스 생성 성공새 리소스가 생성됨 (예: 주문, 도서)
400잘못된 요청필드 검증 실패, 잘못된 파라미터 등
401인증 실패API Key가 없거나 유효하지 않음
402충전금 부족잔액이 부족하여 주문 결제 불가
403권한 없음해당 리소스에 대한 접근 권한 없음
404리소스 없음요청한 리소스를 찾을 수 없음
409충돌중복 요청, 멱등성 키(Idempotency Key) 충돌
429Rate Limit 초과요청 빈도 제한 초과
500서버 에러서버 내부 오류 (재시도 권장)

에러 응답 형식

모든 에러 응답은 동일한 JSON 구조를 따릅니다. success 필드가 false이고,message에 에러 원인이 포함됩니다.

기본 에러 응답

json
{
  "success": false,
  "message": "Unauthorized. Invalid API key.",
  "data": null
}

필드 검증 에러 (400)

요청 본문의 필드 검증에 실패한 경우, fieldErrors 배열에 각 필드별 에러 정보가 포함됩니다.

json
{
  "success": false,
  "message": "Validation failed",
  "fieldErrors": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "recipientName",
      "message": "recipientName is required"
    }
  ]
}

주요 에러 시나리오

인증 실패 (401)

API Key가 누락되었거나 유효하지 않은 경우 반환됩니다.

json
{
  "success": false,
  "message": "Unauthorized. Invalid API key.",
  "data": null
}

충전금 부족 (402)

주문 결제 시 충전금 잔액이 부족한 경우 반환됩니다.

json
{
  "success": false,
  "message": "Insufficient credits. Required: 12500, Available: 5000",
  "data": null
}

리소스 없음 (404)

요청한 리소스(도서, 주문 등)가 존재하지 않거나 접근할 수 없는 경우 반환됩니다.

json
{
  "success": false,
  "message": "Book not found",
  "data": null
}

멱등성 키 충돌 (409)

동일한 Idempotency-Key 헤더로 다른 내용의 요청을 보낸 경우 반환됩니다.

json
{
  "success": false,
  "message": "Idempotency key conflict. A different request was already processed with this key.",
  "data": null
}

Rate Limit 초과 (429)

요청 빈도 제한을 초과한 경우 반환됩니다. Retry-After 헤더를 확인하세요.

json
{
  "success": false,
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "data": null
}

서버 에러 (500)

서버 내부 오류가 발생한 경우 반환됩니다. 잠시 후 재시도하거나 지속될 경우 지원팀에 문의하세요.

json
{
  "success": false,
  "message": "Internal server error",
  "data": null
}

에러 처리 권장사항

  • 4xx 에러: 요청 내용을 수정한 후 재시도하세요. 동일한 요청을 반복해도 같은 에러가 발생합니다.
  • 429 에러: Retry-After 헤더 값만큼 대기 후 재시도하세요. Exponential Backoff를 적용하는 것을 권장합니다.
  • 500 에러: 서버 측 문제이므로 잠시 후 재시도하세요. 지속될 경우 지원팀에 문의하세요.
  • 필드 에러: fieldErrors 배열을 파싱하여 사용자에게 구체적인 수정 안내를 제공하세요.

관련 문서