Errors
API가 반환하는 모든 코드를 발생 영역별로 정리했습니다.
실패 형식
요청이 실패하면 공통 실패 구조가 반환됩니다.
{
"result": false,
"code": 404,
"errorCode": "RESOURCE_005",
"message": "데이터를 찾을 수 없습니다."
}
분기는 errorCode로 합니다. code는 HTTP 상태를 그대로 반복하고, message는 릴리스와 언어에 따라 달라질 수
있는 지역화된 문구이므로 절대 이 값으로 판단하지 않습니다.
라이선스 endpoint는 {"code": number, "error": "ENUM_NAME"}을 반환합니다. web-office의 lock·unlock 실패와
그곳의 권한 실패는 평문 본문을 반환합니다. 한 행이라도 실패한 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 | 다른 권한이 켜져 있는 동안 보기 권한을 끌 수 없음 |
SHARE_001 | 404 | 지정한 사용자에게 리소스가 공유되지 않음 |
SHARE_004 | 404 | 공유를 찾을 수 없음 |
SHARE_007 | 404 | 해당 토큰의 공유 링크가 없음 |
리소스, 파일, 폴더
| 코드 | 상태 | 의미 |
|---|---|---|
RESOURCE_001 | 400, 404 | 삭제 실패. 일부 endpoint에서는 리소스를 찾을 수 없음 |
RESOURCE_005 | 404 | 리소스를 찾을 수 없음 |
RESOURCE_009 | 400 | 휴지통에서 복원 실패 |
RESOURCE_015 | 400 | endpoint에 따라 용량 부족 또는 잠금·잠금 해제 실패 |
RESOURCE_016 | 400 | 잠금 해제 실패. web-office endpoint는 평문으로 반환 |
QUOTA_003 | 400 | 문서를 만들 용량이 부족함 |
QUOTA_004 | 400 | tenant의 가용 용량이 부족함 |
RESOURCE_015는 두 가지 의미로 쓰임파일·문서 endpoint에서는 용량 부족을, 리소스 잠금·잠금 해제 endpoint에서는 잠금 실패를 뜻합니다. 호출한 endpoint와 함께 읽습니다.
버전
| 코드 | 상태 | 의미 |
|---|---|---|
RESOURCE_VERSION_002 | 400 | 버전 삭제 실패 |
RESOURCE_VERSION_003 | 404 | 버전을 찾을 수 없음 |
RESOURCE_VERSION_005 | 500 | 버전 복원 중 예기치 못한 실패 |
휴지통, 중요 문서함, 최근 문서함, 고정 폴더
| 코드 | 상태 | 의미 |
|---|---|---|
TRASH_001 | 400 | 완전 삭제 실패 |
TRASH_CLEAN_UP_001 | 400 | 휴지통 비우기 실패 |
STARRED_001 | 400 | 중요 표시 해제 실패 |
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 | 계정 생성 실패. 외부 키가 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 | 국가 번호와 전화번호는 함께 보내거나 둘 다 생략해야 함 |
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 | 베이스 도메인이 설정되지 않았거나 지정한 베이스 도메인 seq가 없음 |
BASE_DOMAIN_002 | 400 | 유효하지 않은 베이스 도메인 |
BASE_DOMAIN_004 | 400 | 도메인이 등록된 베이스 도메인으로 끝나야 함 |
tenant 설정
| 코드 | 상태 | 의미 |
|---|---|---|
SSO_PROTOCOL_001 | 400 | 지원하지 않는 SSO 프로토콜 |
SSO_PROTOCOL_002 | 400 | 프로토콜 유형과 설정이 일치하지 않음 |
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 발송 실패. 설정을 확인 |
SYSTEM_CONFIG_003 | 404 | 오피스 설정을 찾을 수 없음 |
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을 참고합니다.