에러 코드

API 응답 에러 코드 목록

에러 응답 형식

모든 에러 응답은 다음 형식을 따릅니다:

{
  "error_code": "AUTH_001",
  "message": "인증 토큰이 없습니다.",
  "error": "인증 토큰이 없습니다."
}

필드	설명
`error_code`	구조화된 에러 코드 (카테고리_번호)
`message`	사람이 읽을 수 있는 에러 메시지
`error`	`message`와 동일 (하위 호환성)

HTTP 상태 코드

코드	의미	해당 카테고리
200	성공	-
400	잘못된 요청	VALIDATION, ATTENDANCE(일부), REQUEST(일부), SETTING(일부), TASK(일부)
401	인증 실패	AUTH
402	크레딧 부족	CREDIT
403	권한 없음	PERMISSION, COMPANY(일부), SITE(일부)
404	찾을 수 없음	USER, COMPANY, SITE, MEMBER, EQUIPMENT, FINANCE, SAFETY, TASK, SETTING, FILE, REQUEST
409	충돌/중복	USER(중복), COMPANY(중복), SITE(중복), MEMBER(중복), EQUIPMENT(중복), ATTENDANCE(중복), REQUEST(중복)
500	서버 오류	DATABASE, SERVER

AUTH (인증) - 401

코드	메시지	설명
`AUTH_001`	인증 토큰이 없습니다.	Authorization 헤더에 Bearer 토큰 누락
`AUTH_002`	토큰 검증 실패:	Firebase ID 토큰 유효성 검증 실패
`AUTH_003`	본인인증이 되지 않았습니다.	본인인증 미완료 사용자
`AUTH_004`	테스트 토큰 오류:	테스트 모드 토큰 처리 오류

PERMISSION (권한) - 403

코드	메시지	설명
`PERMISSION_001`	회사 멤버가 아닙니다.	회사 멤버십 없음
`PERMISSION_002`	현장 멤버가 아닙니다.	현장 멤버십 없음
`PERMISSION_003`	권한이 없습니다.	필요 role 미충족
`PERMISSION_004`	해당 현장에 접근 권한이 없습니다.	allowed_sites에 해당 현장 없음
`PERMISSION_005`	페이지 접근 권한이 없습니다.	allowed_pages에 해당 페이지 없음
`PERMISSION_006`	권한이 없습니다.	기타 권한 오류

VALIDATION (입력 검증) - 400

코드	메시지	설명
`VALIDATION_001`	JSON 데이터가 없습니다.	요청 본문이 JSON이 아님
`VALIDATION_002`	필수 필드 '{field}'이(가) 없습니다.	필수 필드 누락
`VALIDATION_003`	필드 '{field}'의 값이 null입니다.	필수 필드가 null
`VALIDATION_004`	필드 '{field}'은(는) {expected_type}이어야 합니다.	타입 불일치
`VALIDATION_005`	필드 '{field}'의 형식이 올바르지 않습니다. (타입: {field_type})	REGEX 검증 실패
`VALIDATION_006`	필드 '{field}'은(는) 최소 {min_length}자 이상이어야 합니다.	최소 길이 미달
`VALIDATION_007`	필드 '{field}'은(는) 최대 {max_length}자까지 가능합니다.	최대 길이 초과
`VALIDATION_008`	필드 '{field}'은(는) {enum_values} 중 하나여야 합니다.	ENUM 값 불일치
`VALIDATION_009`	필드 '{field}'은(는) {min_value} 이상이어야 합니다.	최솟값 미달
`VALIDATION_010`	필드 '{field}'은(는) {max_value} 이하여야 합니다.	최댓값 초과
`VALIDATION_011`	{detail}	범용 검증 에러
`VALIDATION_012`	올바르지 않은 상태입니다.	상태값 오류
`VALIDATION_013`	숫자 필드 형식이 올바르지 않습니다.	숫자 파싱 실패
`VALIDATION_014`	시간 형식이 올바르지 않습니다.	시간 파싱 실패
`VALIDATION_015`	{field}은(는) {ENUM} 중 하나여야 합니다.	전역 ENUM 검증 실패 (v1)
`VALIDATION_016`	{field}의 형식이 올바르지 않습니다.	전역 REGEX 검증 실패 (v1)

USER (사용자) - 404/409

코드	메시지	HTTP
`USER_001`	사용자 정보를 찾을 수 없습니다.	404
`USER_002`	존재하지 않는 유저입니다.	404
`USER_003`	이미 등록된 이메일입니다.	409
`USER_004`	요청자의 인증이 되지 않았습니다.	403

COMPANY (회사) - 404/409

코드	메시지	HTTP
`COMPANY_001`	회사를 찾을 수 없습니다.	404
`COMPANY_002`	이미 기업 소유자입니다.	409
`COMPANY_003`	이미 등록된 기업입니다.	409
`COMPANY_004`	이미 등록된 사업자 등록번호입니다.	409
`COMPANY_005`	관리자가 회사에 속하지 않았습니다.	403

SITE (현장) - 400/404/409

코드	메시지	HTTP
`SITE_001`	존재하지 않는 현장입니다.	404
`SITE_002`	이미 등록된 사이트입니다.	409
`SITE_003`	현장이 활성화 상태가 아닙니다.	400
`SITE_004`	이미 사용 중인 현장명입니다.	409
`SITE_005`	소유자가 회사에 속하지 않았습니다.	403
`SITE_006`	출근 중이므로 현장 변경이 불가합니다.	400
`SITE_007`	출퇴근 요청이 처리 중이므로 현장 변경이 불가합니다.	400
`SITE_008`	현장 변경 요청이 처리 중이므로 출근이 불가합니다.	400

MEMBER (멤버) - 400/404/409

코드	메시지	HTTP
`MEMBER_001`	대상 멤버를 찾을 수 없습니다.	404
`MEMBER_002`	존재하지 않는 회원입니다.	404
`MEMBER_003`	이미 근로자 입니다.	409
`MEMBER_004`	이미 입사 사용자입니다.	409
`MEMBER_005`	해당 회사의 멤버가 아닙니다.	404
`MEMBER_006`	해당 현장의 멤버가 아닙니다.	404
`MEMBER_007`	퇴사 요청자의 멤버 정보를 찾을 수 없습니다.	404
`MEMBER_008`	변경전 현장에서 입사중인 사용자가 아닙니다.	400

EQUIPMENT (장비) - 400/404/409

코드	메시지	HTTP
`EQUIPMENT_001`	장비가 존재하지 않습니다.	404
`EQUIPMENT_002`	이미 배정된 장비입니다.	409
`EQUIPMENT_003`	이미 해제된 장비입니다.	400
`EQUIPMENT_004`	장비 정보를 찾을 수 없습니다.	404
`EQUIPMENT_005`	해당 장비의 소유자가 아닙니다.	403
`EQUIPMENT_006`	해당 현장의 장비 멤버가 아닙니다.	404
`EQUIPMENT_007`	장비 소유자 정보를 찾을 수 없습니다.	404
`EQUIPMENT_008`	이미 배정 요청이 있습니다.	409

ATTENDANCE (출퇴근) - 400/409

코드	메시지	HTTP
`ATTENDANCE_001`	이미 출근 체크 요청이 있습니다.	409
`ATTENDANCE_002`	이미 출근 체크가 되어있습니다.	409
`ATTENDANCE_003`	이미 퇴근 체크가 되어있습니다.	409
`ATTENDANCE_004`	출근 체크가 되어있지 않습니다.	400
`ATTENDANCE_005`	존재하지 않는 출근 로그입니다.	404
`ATTENDANCE_006`	이미 퇴근 처리된 출근 로그입니다.	400
`ATTENDANCE_007`	퇴근 시간은 출근 시간보다 이전일 수 없습니다.	400
`ATTENDANCE_008`	출근 시간이 없습니다.	400
`ATTENDANCE_009`	하루에 출근 요청은 3번까지만 가능합니다.	400
`ATTENDANCE_010`	이미 출퇴근 체크 요청이 있습니다.	409
`ATTENDANCE_011`	출석 DB 오류.	400
`ATTENDANCE_012`	퇴근 요청이 대기 중입니다. 먼저 퇴근 요청을 처리해주세요.	400
`ATTENDANCE_013`	이미 출근중인 대상은 기록을 추가 할 수 없습니다.	400
`ATTENDANCE_014`	요청중인 상태입니다.	400

REQUEST (요청) - 400/404/409

코드	메시지	HTTP
`REQUEST_001`	요청 데이터가 없습니다.	404
`REQUEST_002`	취소할 수 있는 요청이 아닙니다.	400
`REQUEST_003`	이미 대기 중인 요청이 있습니다.	409
`REQUEST_004`	요청 데이터를 찾을 수 없습니다.	404
`REQUEST_005`	{detail}	400

FINANCE (재무) - 404

코드	메시지	HTTP
`FINANCE_001`	해당 노동 대장이 없습니다.	404
`FINANCE_002`	해당 사용자가 없습니다.	404
`FINANCE_003`	존재하지 않는 공급자입니다.	404
`FINANCE_004`	존재하지 않는 기타 비용입니다.	404
`FINANCE_005`	존재하지 않는 기타 비용 내역입니다.	404

CREDIT (크레딧) - 402

코드	메시지	HTTP
`CREDIT_001`	AI 크레딧이 부족합니다. (잔액: {balance}, 필요: {cost})	402

SAFETY (안전) - 400/404

코드	메시지	HTTP
`SAFETY_001`	위험성 평가 문서가 없습니다.	404
`SAFETY_002`	위험성 평가 항목이 없습니다.	404
`SAFETY_003`	문서함이 존재하지 않습니다.	404
`SAFETY_004`	작업 중지권 데이터가 없습니다.	404
`SAFETY_005`	건의 사항 데이터가 없습니다.	404
`SAFETY_006`	긴급 알림 데이터가 없습니다.	404
`SAFETY_007`	{detail}	400

TASK (작업) - 400/404

코드	메시지	HTTP
`TASK_001`	작업 데이터가 없습니다.	404
`TASK_002`	존재하지 않는 작업입니다.	404
`TASK_003`	존재하지 않는 로그입니다.	404
`TASK_004`	공수는 0 이상이어야 합니다.	400

SETTING (설정) - 400/404

코드	메시지	HTTP
`SETTING_001`	태그 설정을 찾을 수 없습니다.	404
`SETTING_002`	존재하지 않는 직종입니다:	400
`SETTING_003`	존재하지 않는 직급입니다:	400
`SETTING_004`	존재하지 않는 업체입니다:	400
`SETTING_005`	{detail}	400

FILE (파일) - 400/404

코드	메시지	HTTP
`FILE_001`	파일을 찾을 수 없습니다:	404
`FILE_002`	파일 경로가 올바르지 않습니다:	400
`FILE_003`	첨부파일 삭제 실패	400

DATABASE (데이터베이스) - 500

코드	메시지	설명
`DATABASE_001`	DB 쓰기 오류 발생:	write 실패
`DATABASE_002`	DB get 조회 오류 발생:	get 쿼리 실패
`DATABASE_003`	DB 문서 조회 오류 발생:	get_by_id 실패
`DATABASE_004`	DB 업데이트 오류 발생:	update 실패
`DATABASE_005`	DB 삭제 오류 발생:	delete 실패
`DATABASE_006`	SALT가 제공되지 않았습니다.	해시 비교 시 SALT 누락

SERVER (서버) - 500

코드	메시지	설명
`SERVER_001`	서버 오류 발생:	범용 서버 오류
`SERVER_002`	json-text 변환 중 오류 발생:	JSON 직렬화 실패
`SERVER_003`	데이터 형식 변환 중 오류 발생:	데이터 coercion 실패
`SERVER_004`	메일 전송 중 오류 발생:	이메일 발송 실패
`SERVER_005`	계정 생성 실패:	Firebase Auth 계정 생성 실패