오류 처리

오류 유형은 크게 두 가지로 구분할 수 있습니다.

• (A) API 요청 오류
  • HTTP 응답 상태코드 4xx, 5xx
  • 작업 전체실패
• (B) API 요청 성공, 데이터 출력실패
  • HTTP 응답 상태코드 200
  • 작업 부분실패 (다건 요청시 일부 사업자정보 요청만 실패할 수 있음)

(A) API 요청 오류, 작업 전체실패

HTTP 응답코드가 200이 아닐 때

응답코드는 클라이언트 요청에서 발생한4xx 오류와, 서버에서 발생한 5xx 오류로 구분할 수 있습니다.

전체실패 오류가 발생했을 때 서버는 다음과 같은 JSON 응답을 반환합니다.

{
  "errorId": "1d8ea2b0-1fc5-4fa8-9d61-539afc642471",
  "error": "Unauthorized",
  "message": "인증토큰을 확인해주세요"
}

사업자정보 API에서 사용하는 HTTP 응답코드와 오류코드를 정리하면 다음과 같습니다

HTTP 응답코드	오류코드 (응답본문의 error)	상황
400	Bad Request	요청 형식이 맞지 않을 때 (필수항목 누락 ...)
401	Unauthorized	인증 실패 (인증 토큰 누락 ...)
403	Forbidden	접근권한 없는 경우
429	Too Many Requests	요청 속도 초과, 일 조회한도 초과
500	Internal Server Error	처리되지 않은 서버 오류
503	Service Unavailable	서버 점검, 연계기관 연동 오류 등 ...
504	Gateway Timeout	연결대기시간 초과, 네트워크 오류 등 ...

(B) API 요청 성공, 작업 부분실패

HTTP 응답코드는 200이지만, 개별 조회 오류가 발생한 경우

부분실패 오류가 발생했을 때 서버는 다음과 같은 JSON 응답을 반환합니다 (성공 1건, 실패 2건)

[
  {
    "reqBizNo": "6428700732",
    "info": {
      // 사업자정보 데이터 ... (생략)
    },
    "error": null
  },
  {
    "reqBizNo": "0000000000",
    "info": null,
    "error": "UnregisteredBiz"
  },
  {
    "reqBizNo": "1248100998",
    "info": null,
    "error": "QueryUnavailable"
  }
]

사업자정보 API에서 사용하는 부분실패 오류코드를 정리하면 다음과 같습니다

오류코드	상황
UnregisteredBiz	미등록 사업자 조회 요청
QueryTimeout	응답 대기시간 초과 (30초)
QueryUnavailable	연계기관 점검 등으로 인한 실시간 조회불가 오류
UndefinedError	나열된 오류에 해당하지 않는 기타 오류