OneAsset Dashboard

공통 에러 응답 구조

현재 백엔드 `ErrorResult`는 `code`, `type`, `title`, `status`, `instance`를 반환합니다. `detail`은 프론트 타입에서 optional로 허용하지만, 현재 MVP1 응답에는 포함되어 있지 않습니다.

{
  "success": false,
  "error": {
    "code": "PROJECT_NOT_FOUND_404",
    "type": "/errors/project/not-found",
    "title": "Project not found",
    "status": 404,
    "instance": "/api/projects/{projectId}"
  }
}

HTTP status별 기본 정책

Status	의미	프론트 처리
400	입력값 또는 도메인 검증 오류	폼 inline error 또는 요청 실패 메시지
401	인증 실패	Dashboard JWT는 로그인 이동, Developer API key는 키 재발급 안내
403	권한 없음	접근 불가 화면과 목록 복귀 액션
404	리소스 없음	empty state와 목록 복귀 액션
409	상태 충돌	refetch 후 최신 상태 기준으로 안내
500	서버 오류	page error와 재시도 버튼

에러 코드별 설명

Common · HTTP 400

COMMON_INVALID_INPUT_400

/errors/common/invalid-input

백엔드 title: Invalid input
언제 발생하나: 요청 body, query parameter, form 값이 유효하지 않을 때 발생합니다.
프론트 UI: form inline error로 표시하고 사용자가 입력을 수정하게 합니다.

Common · HTTP 400

COMMON_INVALID_ID_400

/errors/common/invalid-id

백엔드 title: Invalid id
언제 발생하나: projectId, apiKeyId, assetId처럼 UUID 형식이어야 하는 값이 잘못됐을 때 발생합니다.
프론트 UI: 잘못된 URL 또는 요청으로 안내하고 목록 복귀 액션을 제공합니다.

Auth · HTTP 401

AUTH_REQUIRED_JWT_CLAIM_MISSING_401

/errors/auth/required-jwt-claim-missing

백엔드 title: Required JWT claim is missing
언제 발생하나: Dashboard API에서 Cognito JWT의 필수 claim(sub, email, name 등)이 없을 때 발생합니다.
프론트 UI: 저장된 토큰을 삭제하고 로그인 페이지로 이동합니다.

Auth · HTTP 401

AUTH_INVALID_API_KEY_401

/errors/auth/invalid-api-key

백엔드 title: Invalid API key
언제 발생하나: Developer API 요청의 X-OneAsset-Api-Key가 없거나 유효하지 않을 때 발생합니다.
프론트 UI: Dashboard가 아니라 외부 앱/서버 설정 문제로 안내합니다. raw key 재발급을 유도합니다.

Auth · HTTP 401

AUTH_INVALID_PROCESSOR_CALLBACK_TOKEN_401

/errors/auth/invalid-processor-callback-token

백엔드 title: Invalid processor callback token
언제 발생하나: 내부 processor callback token이 잘못됐을 때 발생합니다. 일반 Dashboard 사용자가 직접 해결할 수 없습니다.
프론트 UI: 사용자 화면에는 서버 처리 실패로 안내하고 운영 로그 확인 대상으로 분류합니다.

Project · HTTP 403

PROJECT_ACCESS_DENIED_403

/errors/project/access-denied

백엔드 title: Project access denied
언제 발생하나: 인증된 사용자가 해당 프로젝트의 멤버가 아니거나 접근 권한이 없을 때 발생합니다.
프론트 UI: 권한 없음 page state를 보여주고 프로젝트 목록으로 돌아가는 액션을 제공합니다.

Project · HTTP 404

PROJECT_NOT_FOUND_404

/errors/project/not-found

백엔드 title: Project not found
언제 발생하나: projectId에 해당하는 프로젝트가 없거나 삭제되어 조회할 수 없을 때 발생합니다.
프론트 UI: 리소스 없음 상태로 표시하고 프로젝트 목록 링크를 제공합니다.

Project · HTTP 400

PROJECT_INVALID_AUDIT_TIME_400

/errors/project/invalid-audit-time

백엔드 title: Invalid project audit time
언제 발생하나: 프로젝트 생성/수정 감사 시간이 도메인 규칙에 맞지 않을 때 발생합니다.
프론트 UI: 사용자가 직접 수정하기 어렵기 때문에 요청 실패 inline error와 재시도를 제공합니다.

Project · HTTP 409

PROJECT_DELETED_CANNOT_BE_CHANGED_409

/errors/project/deleted-cannot-be-changed

백엔드 title: Deleted project cannot be changed
언제 발생하나: 삭제된 프로젝트를 변경하려 할 때 발생하는 상태 충돌입니다.
프론트 UI: 충돌 메시지를 표시하고 최신 프로젝트 목록을 다시 불러옵니다.

API Key · HTTP 404

API_KEY_NOT_FOUND_404

/errors/api-key/not-found

백엔드 title: API key not found
언제 발생하나: apiKeyId에 해당하는 API Key가 없을 때 발생합니다.
프론트 UI: 목록을 refetch하고 이미 삭제/폐기되었을 수 있음을 안내합니다.

API Key · HTTP 409

API_KEY_REVOKED_CANNOT_BE_CHANGED_409

/errors/api-key/revoked-cannot-be-changed

백엔드 title: Revoked API key cannot be changed
언제 발생하나: 이미 폐기된 API Key를 다시 변경하려 할 때 발생합니다.
프론트 UI: 폐기 완료 상태로 목록을 갱신하고 destructive action을 비활성화합니다.

API Key · HTTP 400

API_KEY_INVALID_AUDIT_TIME_400

/errors/api-key/invalid-audit-time

백엔드 title: Invalid API key audit time
언제 발생하나: API Key 감사 시간이 도메인 규칙에 맞지 않을 때 발생합니다.
프론트 UI: 요청 실패 inline error로 표시하고 운영 로그 확인 대상으로 분류합니다.

API Key · HTTP 400

API_KEY_INVALID_STATUS_400

/errors/api-key/invalid-status

백엔드 title: Invalid API key status
언제 발생하나: API Key 상태 값이 허용된 enum과 맞지 않을 때 발생합니다.
프론트 UI: 목록을 refetch하고 상태 표시 fallback을 사용합니다.

Asset · HTTP 404

ASSET_NOT_FOUND_404

/errors/assets/not-found

백엔드 title: Asset not found
언제 발생하나: key에 해당하는 Asset이 없거나 삭제되어 조회할 수 없을 때 발생합니다.
프론트 UI: Asset not found empty state와 Asset Browser로 돌아가기 액션을 제공합니다.

Asset · HTTP 409

ASSET_INVALID_STATUS_TRANSITION_409

/errors/asset/invalid-status-transition

백엔드 title: Invalid asset status transition
언제 발생하나: Asset 상태가 허용되지 않는 순서로 변경될 때 발생합니다. 예를 들어 삭제/처리 상태 전이가 도메인 규칙과 맞지 않는 경우입니다.
프론트 UI: 상태 충돌로 안내하고 asset detail/list를 refetch합니다.

Asset · HTTP 409

ASSET_DELETED_CANNOT_BE_CHANGED_409

/errors/asset/deleted-cannot-be-changed

백엔드 title: Deleted asset cannot be changed
언제 발생하나: 이미 삭제된 Asset을 다시 변경하려 할 때 발생합니다.
프론트 UI: 삭제된 Asset으로 안내하고 목록으로 이동합니다.

Asset · HTTP 400

ASSET_INVALID_AUDIT_TIME_400

/errors/asset/invalid-audit-time

백엔드 title: Invalid asset audit time
언제 발생하나: Asset 감사 시간이 도메인 규칙에 맞지 않을 때 발생합니다.
프론트 UI: 사용자 입력 문제가 아니므로 일반 요청 실패와 재시도 액션을 제공합니다.

Asset · HTTP 400

ASSET_INVALID_SIZE_400

/errors/asset/invalid-size

백엔드 title: Invalid asset size
언제 발생하나: Asset 파일 크기가 0 이하이거나 도메인 규칙에 맞지 않을 때 발생합니다.
프론트 UI: 업로드한 파일 크기를 확인하도록 안내합니다.

Asset Variant · HTTP 400

ASSET_VARIANT_INVALID_SIZE_400

/errors/asset-variant/invalid-size

백엔드 title: Invalid asset variant size
언제 발생하나: WebP/Thumbnail 같은 변환본 크기 값이 도메인 규칙에 맞지 않을 때 발생합니다.
프론트 UI: Dashboard 사용자가 직접 해결하기 어렵기 때문에 처리 실패로 안내하고 운영 로그 확인 대상으로 분류합니다.

User · HTTP 400

USER_INVALID_AUDIT_TIME_400

/errors/user/invalid-audit-time

백엔드 title: Invalid user audit time
언제 발생하나: User 감사 시간이 도메인 규칙에 맞지 않을 때 발생합니다.
프론트 UI: 프로필 조회/동기화 실패로 안내하고 재시도 버튼을 제공합니다.

User · HTTP 409

USER_NOT_ACTIVE_409

/errors/user/not-active

백엔드 title: User is not active
언제 발생하나: 로컬 User가 활성 상태가 아닐 때 발생합니다.
프론트 UI: 계정 상태 문제로 안내하고 로그아웃 또는 관리자 문의 동선을 제공합니다.

Common · HTTP 500

COMMON_DATA_ACCESS_ERROR_500

/errors/common/data-access-error

백엔드 title: Data access error
언제 발생하나: DB 접근 오류입니다. 사용자가 직접 해결할 수 없는 서버 문제입니다.
프론트 UI: page error state와 재시도 버튼을 제공합니다.

Common · HTTP 500

COMMON_INTERNAL_SERVER_ERROR_500

/errors/common/internal-server-error

백엔드 title: Internal server error
언제 발생하나: 예상하지 못한 서버 내부 오류입니다.
프론트 UI: page error state와 재시도 버튼을 제공하고 운영 로그 확인 대상으로 분류합니다.

에러 처리 레퍼런스

공통 에러 응답 구조

HTTP status별 기본 정책

에러 코드별 설명

COMMON_INVALID_INPUT_400

COMMON_INVALID_ID_400

AUTH_REQUIRED_JWT_CLAIM_MISSING_401

AUTH_INVALID_API_KEY_401

AUTH_INVALID_PROCESSOR_CALLBACK_TOKEN_401

PROJECT_ACCESS_DENIED_403

PROJECT_NOT_FOUND_404

PROJECT_INVALID_AUDIT_TIME_400

PROJECT_DELETED_CANNOT_BE_CHANGED_409

API_KEY_NOT_FOUND_404

API_KEY_REVOKED_CANNOT_BE_CHANGED_409

API_KEY_INVALID_AUDIT_TIME_400

API_KEY_INVALID_STATUS_400

ASSET_NOT_FOUND_404

ASSET_INVALID_STATUS_TRANSITION_409

ASSET_DELETED_CANNOT_BE_CHANGED_409

ASSET_INVALID_AUDIT_TIME_400

ASSET_INVALID_SIZE_400

ASSET_VARIANT_INVALID_SIZE_400

USER_INVALID_AUDIT_TIME_400

USER_NOT_ACTIVE_409

COMMON_DATA_ACCESS_ERROR_500

COMMON_INTERNAL_SERVER_ERROR_500