Sparse space map APIs 오류 코드 설명

Response format

모든 API 응답은 통일된 JSON 형식으로 제공되며, 다음은 예시입니다:

{

  "statusCode": 119,

  "msg": "Parameter has errors",

  "date": "2022-06-15T09:56:30.000Z",

  "result":  //statusCode가 0인 경우에만 result 존재, 오류 발생 시 결과 필드는 비어 있음

}

필드	유형	설명
statusCode	integer	비즈니스 상태 코드. 0은 성공, 0이 아닌 값은 오류
msg	string	메시지
result	object	반환 내용. 상태 코드가 0일 때 대상 객체 구조를 응답하며, 그 외에는 비어 있음
date	string	서버 시간

중요

statusCode == 0 조건에서만 result에 응답 내용이 포함되며, 다른 상태에서는 result가 비어 있습니다.
statusCode != 0 조건에서는 오류 메시지 msg를 확인해야 합니다.

오류 코드 분류

HTTP 상태 코드 설명

HTTP 상태 코드	설명
200	요청 성공 (비즈니스 오류 포함 가능)
400	요청 매개변수 오류
401	APIKey 인증 실패
403	권한 부족 또는 리소스 접근 금지
404	요청 URL 인터페이스 경로 존재하지 않음
500	서버 내부 오류
502	애플리케이션 예외 발생, 데이터 오류 가능성 있음

참고: 비즈니스 오류는 일반적으로 HTTP 200 응답으로 반환되며, statusCode 필드에서 구체적인 오류 유형을 식별합니다.

비즈니스 상태 코드 목록

Status Code	Message
0	Success
101	업로드된 파일이 비어 있음
102	파일 크기가 너무 큼
106	매개변수 누락 또는 매개변수가 비어 있음
110	서버 API 호출 오류
111	리소스를 찾을 수 없음
401	인증 토큰 만료
401	인증 매개변수 누락
401	알 수 없는 appId 또는 appKey
401	계정이 잠김
401	인증 실패, 유효하지 않은 서명 또는 토큰

일반적인 오류 시나리오

타임아웃 응답 없음

Request Timeout: 네트워크 속도 저하. 클라이언트 네트워크 환경 점검 권장

인증 관련 오류

Http 401 Unauthorized: APIKey 인증 실패. appId/appKey 정확성 확인 필요
상태 코드 401: 애플리케이션 키 무효 또는 애플리케이션 미존재. 애플리케이션 설정 점검

매개변수 오류

400 Bad Request: 요청 매개변수 형식 오류

리소스 작업 오류

상태 코드 10x: 조회 대상 리소스 미존재 또는 매개변수 오류

시스템 오류

Http 50x Internal Server Error: 서버 내부 예외 또는 애플리케이션 예외 발생. 웹사이트 또는 샘플 테스트 권장

최적의 실무 권장사항

클라이언트 처리: HTTP 상태 코드만 의존하지 않고 statusCode 필드를 기준으로 비즈니스 성공 여부 판단 권장
오류 재시도: 5xx 오류에 대해서는 적절한 재시도 가능. 4xx 오류는 요청 매개변수 점검 필요
로그 기록: 문제 해결을 위해 완전한 오류 응답 기록 권장
타임아웃 처리: 과도한 대기 방지를 위해 합리적인 요청 타임아웃 시간 설정

Table of Contents