Errors

API가 반환하는 모든 오류 코드를 기능 영역별로 정리했습니다.

실패 형식

요청이 실패하면 공통 실패 구조로 응답합니다.

Failure
{
  "result": false,
  "code": 404,
  "errorCode": "RESOURCE_005",
  "message": "데이터를 찾을 수 없습니다."
}

오류 처리는 errorCode를 기준으로 구현하세요. code는 HTTP 상태 코드와 같은 값입니다. message는 릴리스와 언어에 따라 달라질 수 있는 문구이므로 오류를 판단하는 데 사용하지 않습니다.

공통 실패 구조를 사용하지 않는 응답

라이선스 endpoint는 {"code": number, "error": "ENUM_NAME"} 형식으로 응답합니다. web-office의 lock·unlock 실패와 해당 endpoint의 권한 오류는 일반 텍스트로 응답합니다. CSV 가져오기에서 한 행이라도 실패하면 text/csv 파일을 반환합니다. 감사 로그 내보내기 실패 응답은 공통 구조를 사용하지만 errorCode가 없습니다. 실패 응답을 JSON으로 파싱하기 전에 상태 코드와 Content-Type을 확인하세요.

같은 errorCode가 여러 HTTP 상태 코드와 함께 반환될 수 있으며, endpoint에 따라 비슷하지만 서로 다른 상황에 같은 코드를 사용하기도 합니다. 이러한 경우는 아래 표에 함께 표시했습니다.

요청과 응답

코드	상태	의미
`REQUEST_001`	400	요청 값 검증 실패. `message`에 고정 문구 대신 검증에 실패한 필드 목록이 포함됨
`REQUEST_006`	403	API Key의 tenant와 요청한 host의 tenant가 다름
`RESPONSE_001`	500	예기치 않은 서버 오류
`AUTH_009`	403	호출한 키가 역할 또는 scope 검사를 통과하지 못함

인증과 API Key

코드	상태	의미
`API_KEY_001`	404	관리할 수 없는 키. 존재하지 않거나 호출한 경로의 관리 범위를 벗어남
`API_KEY_004`	401	인증 실패. 헤더 누락, 등록되지 않은 값, 비활성화·만료된 키, 비활성화된 계정, 다른 tenant의 도메인
`API_KEY_006`	400	대상 계정이 지정한 tenant에 속하지 않음
`API_KEY_007`	400	발급 대상 계정에 tenant를 지정해야 함
`API_KEY_010`	400	지원하지 않거나 허용되지 않는 scope 조합
`API_KEY_011`	400	슈퍼 관리자 키에는 tenant를 지정할 수 없음
`API_KEY_012`	403	같은 역할의 다른 계정에는 키를 발급할 수 없음
`API_KEY_013`	403	슈퍼 관리자는 슈퍼 관리자 발급 endpoint를 사용해야 함

각 코드가 반환되는 상황은 Authentication을 참고하세요.

권한과 공유

코드	상태	의미
`PERMISSION_001`	403	호출한 계정에 공유되지 않은 리소스
`PERMISSION_002`	403	리소스에 접근 권한이 없음
`PERMISSION_003`	400	보기 권한(`cv`)은 `false`로 보낼 수 없음
`PERMISSION_005`	403	해당 공유 유형에서 허용하지 않는 권한을 `true`로 보냄
`SHARE_001`	404	지정한 사용자에게 리소스가 공유되지 않음
`SHARE_004`	404	공유 정보를 찾을 수 없음
`SHARE_005`	500	공유 변경 실패
`SHARE_007`	404	해당 토큰의 공유 링크가 없음
`SHARE_008`	400	상위 또는 하위 리소스에 다른 공유 유형의 공유가 있음
`SHARE_009`	500	공유 생성 실패
`SHARE_011`	403	tenant가 `SPECIFIC_USERS` 공유를 허용하지 않음
`SHARE_012`	403	공유 기능이 비활성화됨
`SHARE_013`	403	허용되지 않은 공유 유형
`SHARE_014`	403	tenant 외부 공유가 허용되지 않음
`SHARE_TARGET_001`	500	공유 대상 설정 실패

리소스, 파일, 폴더

코드	상태	의미
`RESOURCE_001`	400, 404	삭제 실패. 일부 endpoint에서는 리소스를 찾을 수 없다는 의미로도 사용
`RESOURCE_002`	400	이동 실패
`RESOURCE_005`	404	리소스를 찾을 수 없음
`RESOURCE_006`	409	같은 이름의 리소스가 이미 있음
`RESOURCE_009`	400	휴지통에서 복원 실패
`RESOURCE_014`	400	이 업로드 유형에는 `rs`가 필요함
`RESOURCE_015`	400	잠금 실패
`RESOURCE_016`	400	잠금 해제 실패
`RESOURCE_LOCK_ASPECT_002`	423	리소스가 잠겨 있음
`FILE_002`	404	요청한 언어의 문서 템플릿이 없음
`QUOTA_003`	400	용량이 부족함
`QUOTA_004`	400	tenant의 가용 용량이 부족함

버전

코드	상태	의미
`RESOURCE_VERSION_002`	400	버전 삭제 실패
`RESOURCE_VERSION_003`	404	버전을 찾을 수 없음
`RESOURCE_VERSION_006`	500	버전 복원 실패

휴지통, 중요 문서함, 최근 문서함, 고정 폴더

코드	상태	의미
`TRASH_001`	400	완전 삭제 실패
`TRASH_CLEAN_UP_001`	400	휴지통 비우기 실패
`STARRED_001`	400	중요 표시 해제 실패
`STARRED_002`	409	이미 중요 문서함에 등록된 리소스
`PINNED_FOLDER_001`	400	고정 해제 실패. 본인이 고정한 폴더가 아니거나 이미 해제됨
`PINNED_FOLDER_002`	409	이미 고정된 폴더
`PINNED_FOLDER_003`	400	고정 폴더는 최대 3개

알림

코드	상태	의미
`NOTIFICATION_002`	500	읽음 처리 실패. 알림이 없거나 본인의 알림이 아님
`NOTIFICATION_003`	500	읽지 않음 처리 실패. 알림이 없거나 본인의 알림이 아님

계정

코드	상태	의미
`USER_001`	400	비밀번호가 규칙에 맞지 않음
`USER_002`	400	이메일 형식이 잘못됨
`USER_004`	409	이미 사용 중인 계정 id
`USER_005`	404	계정을 찾을 수 없거나 다른 tenant 소속
`USER_007`	400	프로필 이미지 업로드 실패
`USER_008`	404	등록된 프로필 이미지가 없음
`USER_009`	400	입력한 현재 비밀번호가 일치하지 않음
`USER_010`	400	새 비밀번호가 이전 비밀번호와 같음
`USER_011`	403	기본 관리자와 본인 계정은 비활성화할 수 없음
`USER_012`	403	기본 관리자와 본인 계정은 삭제할 수 없음
`USER_013`	500	계정 생성 실패. API Key로 `ADMIN` 계정 생성을 요청했거나 라이선스 사용자 수를 모두 사용함
`USER_014`	400	현재 사용량보다 작은 용량으로 설정할 수 없음
`USER_015`	400	프로필 이미지 삭제 실패
`USER_016`	400	계정 삭제 대기 처리 실패
`USER_017`	400	활성화 실패
`USER_018`	400	비활성화 실패
`USER_019`	400	요청한 상태 필터 값이 유효하지 않음
`USER_022`	400	MFA 초기화 실패 또는 비밀번호 재설정 토큰이 유효하지 않음
`USER_023`	400	비밀번호 재설정 토큰이 만료됨
`USER_025`	404	수정할 계정을 찾을 수 없음
`USER_026`	400	등록 시 필수 항목이 누락됨
`USER_027`	400	국가 번호와 전화번호는 함께 보내거나 둘 다 생략해야 함
`USER_028`	400	요청한 권한 필터 값이 올바르지 않음
`ADMIN_USER_001`	400	복원 실패. 계정이 삭제 대기 상태가 아님
`ADMIN_USER_002`	400	요청한 계정 중 삭제 대기 상태가 아닌 계정이 있음

USER_022의 두 가지 의미

관리자 endpoint에서는 MFA 초기화 실패를, 사용자 endpoint에서는 유효하지 않은 비밀번호 재설정 토큰을 뜻합니다. 한 endpoint에서 두 의미가 함께 사용되지는 않습니다.

USER_005는 존재하지 않는 계정뿐 아니라 다른 tenant의 계정에도 반환됩니다. 따라서 다른 tenant에 특정 계정이 있는지 알 수 없습니다.

tenant와 도메인

코드	상태	의미
`TENANT_001`	404	tenant를 찾을 수 없음
`TENANT_006`	409	이미 사용 중인 도메인
`TENANT_007`	400	유효하지 않은 도메인
`BASE_DOMAIN_001`	404	`bs`에 지정한 베이스 도메인 seq가 없음
`BASE_DOMAIN_002`	400	유효하지 않은 베이스 도메인
`BASE_DOMAIN_004`	400	도메인이 등록된 베이스 도메인으로 끝나지 않음

tenant 설정

코드	상태	의미
`SSO_PROTOCOL_001`	400	지원하지 않는 SSO 프로토콜
`SSO_PROTOCOL_002`	400	프로토콜 유형과 설정이 일치하지 않음
`SSO_PROTOCOL_JWT_002`	409	다른 JWT provider가 같은 issuer를 사용 중
`SSO_PROVIDER_001`	404	SSO provider를 찾을 수 없음
`SSO_PROVIDER_005`	409	활성화된 JWT provider가 이미 있음. `ssoProviderSeq`를 지정해 수정해야 함
`SSO_PROVIDER_006`	409	슈퍼 관리자가 로그인 설정을 모든 tenant에 적용 중
`ACCESS_002`	400	유효하지 않은 국가 코드
`ACCESS_003`	400	제한을 켜기 전에 국가나 주소를 하나 이상 등록해야 함
`ACCESS_004`	400	유효하지 않은 IP 주소 또는 CIDR
`BRANDING_001`	404	브랜딩 설정이나 등록된 이미지를 찾을 수 없음
`BRANDING_002`	500	이미지 변환 실패
`SMTP_CONFIG_001`	404	등록된 SMTP 설정이 없음
`SMTP_CONFIG_002`	500	SMTP 발송 실패. SMTP 설정을 확인해야 함
`SYSTEM_CONFIG_003`	404	Office 설정을 찾을 수 없음
`SYSTEM_CONFIG_008`	403	다중 tenant 환경에서는 슈퍼 관리자만 일반 설정을 변경할 수 있음
`STORAGE_002`	500	다운로드 실패
`STORAGE_006`	404	해당 스토리지 키가 없음

라이선스

라이선스 endpoint는 별도의 숫자 코드를 사용하며 {"code": number, "error": "ENUM_NAME"} 형식으로 응답합니다.

코드	`error`	의미
`6999`	`LICENSE`	라이선스 처리 중 예기치 않은 오류
`6998`	`LICENSE_FILE_NOT_EXIST`	등록된 라이선스가 없음
`6997`	`LICENSE_FILE_NOT_VALID_FORMAT`	라이선스 파일 형식이 유효하지 않음
`6996`	`LICENSE_MANAGER_AUTHENTICATION_FAILED`	라이선스 매니저 인증 실패
`6995`	`LICENSE_FILE_EXPIRATION`	라이선스 만료
`6994`	`LICENSE_UNDER_LIMIT`	만료 임박. 성공한 상태 조회 응답에 포함됨
`6993`	`LICENSE_EXCEED_LIMIT`	허용 사용자 수 초과. 성공한 상태 조회 응답에 포함됨
`4999`	`DB`	업로드된 파일 읽기 실패

6994와 6993은 HTTP 오류가 아니며, 성공한 라이선스 상태 조회 응답의 code 값으로 반환됩니다. 자세한 내용은 Admin을 참고하세요.

실패 형식​

요청과 응답​

인증과 API Key​

권한과 공유​

리소스, 파일, 폴더​

버전​

휴지통, 중요 문서함, 최근 문서함, 고정 폴더​

알림​

계정​

tenant와 도메인​

tenant 설정​

라이선스​