오류 처리
오류 응답의 형식과 서비스별 HTTP 상태 코드를 통합해 설명합니다.
오류 응답 형식
오류 응답은 발생 위치에 따라 형태가 다릅니다.
| 형태 | 발생 위치 | 예시 |
|---|---|---|
| 인증·권한 오류 | 401, 403 | {"error": "Forbidden", "message": "Policy denied", "requestId": "..."} |
| 봉투형 | 로그인, 키 검증, IAM 인가(AuthZ) | {"result": null, "message": "...", "timestamp": "...", "requestId": "...", "code": "ACCOUNT_LOCKED"} (code는 일부 인증 오류만) |
| 단순형 | 서비스 계정·키 관리 API | {"detail": "service account not found: sa-..."} |
컴퓨트·컨테이너·네트워크 API의 오류는 표준 봉투에 result: null + message 형태입니다. 오류 코드 필드가 없으므로 아래 HTTP 상태로 분기하십시오.
재시도 원칙
5xx는 일시 장애이므로 지수 백오프로 재시도하고, 401/403은 자격증명·권한 문제이므로 재시도 대신 원인을 점검하십시오. 409는 대부분 "이미 그 상태"이거나 잠금 상태를 의미하는 신호입니다. 업스트림 인프라 오류는 대부분 502 하나로 축약되어 전달되므로, 5xx 계열은 원인 세분화보다 재시도 여부로 판단하십시오.
HTTP 상태 코드 (공통)
| 상태 | 의미 |
|---|---|
| 400 | 잘못된 요청 |
| 401 | 인증 실패 |
| 403 | 권한 없음 |
| 404 | 없음 |
| 409 | 충돌 |
| 422 | 검증 실패 |
| 429 | 요청 제한 |
| 5xx | 서버 오류 |
서비스별 발생 조건
인스턴스(VM) — 컴퓨트
| 상태 | 발생 조건 |
|---|---|
| 401 / 403 | 인증 실패 / 권한 없음(정책 거부), 도메인·볼륨 AZ 불일치 |
| 404 | 인스턴스 없음 |
| 409 | 잠금(locked), 허용되지 않는 상태 전이 |
| 413 | 쿼터 초과(인스턴스·볼륨·이미지·키 페어·서버 그룹 생성). 구성요소마다 다른 초과 사유를 413 하나로 정규화 |
| 422 | 검증 실패, 필수 헤더 누락, 미정의 필드 |
| 500 / 502 | 내부 오류 / 인프라 오류 |
요청에 정의되지 않은 필드가 있으면 항상 422입니다(엄격 검증). 413은 재시도 대상이 아니라 쿼터 상향이 필요하다는 신호입니다. 자세한 내용은 컴퓨트 레퍼런스를 참조하십시오.
Kubernetes 클러스터 — 컨테이너
| 상태 | 발생 조건 |
|---|---|
| 400 | 등록 시 domainId와 X-Domain-Id 불일치, 검증 실패 |
| 401 / 403 | 인증 실패 / 권한 없음(정책 거부) |
| 404 | 클러스터 없음/삭제됨, kubeconfig 없음 |
| 409 | 삭제 불가 상태, App Catalog 앱 잔존 |
| 422 | 본문·쿼리 검증 실패, 필수 헤더 누락 |
| 500 / 502 / 504 | 내부 오류 / 의존 서비스 오류 / LB·볼륨 대기 시간 초과 |
워크로드(Pod·Deployment 등)
| 상태 | 발생 조건 |
|---|---|
| 401 | 인증 실패 |
| 403 | 권한 없음 |
| 404 | 리소스 없음 |
| 409 | 이름 충돌 등 |
| 422 | 검증 실패, 정의되지 않은 파라미터·필드 |
| 500 | 내부 오류 |
| 502 | 인프라(클러스터) 통신 오류 |
Namespace·Service·Ingress를 포함해 워크로드 계열 API는 동일한 상태 매핑을 공유합니다. 자세한 내용은 컨테이너 레퍼런스를 참조하십시오.
네트워크
| 상태 | 발생 조건 |
|---|---|
| 400 | X-Partition-Id 누락, Floating IP 연결 요청의 필드 조합 위반 |
| 401 | 인증 실패 |
| 403 | 권한 없음, origin이 컨테이너 서비스로 표시된 보안 그룹의 수정·규칙 삭제 시도 |
| 404 | 리소스 없음(네트워크·서브넷·라우터·Floating IP·보안 그룹·규칙) |
| 409 | 리소스 충돌, 사용 중인 리소스 삭제 시도, 중복 규칙 생성 |
| 413 | 쿼터 초과(보안 그룹·규칙 생성) |
| 422 | 요청 검증 실패, 정의되지 않은 필드, 수정 항목 0개 |
| 502 | 인증 컨텍스트 확인 중 외부 시스템 오류 |
| 503 | 라우터 동시 수정 잠금 획득 실패(주로 라우터 삭제). 잠시 후 재시도하십시오 |
네트워크 API의 400 vs 422
네트워크 API는 X-Partition-Id 누락을 400으로 응답합니다. 컴퓨트·컨테이너 API는 같은 상황을 422로 응답하므로, 서비스별로 분기 로직을 다르게 두어야 합니다. 자세한 내용은 네트워크 레퍼런스를 참조하십시오.
인증(AuthN)·인가(AuthZ) 관련 오류
| 상태 | 상황 |
|---|---|
| 401 | 로그인 자격증명·조직 오류(사유 비구분), API 키 없음/비활성/만료/secret 불일치 |
| 429 | 로그인·MFA·비밀번호 재설정 경로의 시도 제한 초과(계정 잠금 시 ACCOUNT_LOCKED) |
| 502 | 인증 서버 일시 장애 |
서비스 계정·API 키 발급 절차와 403 점검 순서는 인증 준비를 참조하십시오.