SEcMS Error Code Catalog

모든 에러 응답은 {"error": "...", "code": "...", "message": "..."} 형태.
디버깅 가이드: 각 코드별 원인 → 해결 명시.

Auth & Permission (1xxx)

Code	HTTP	원인	해결
AUTH_TOKEN_MISSING	401	Authorization 헤더 부재	`Bearer <Firebase JWT>` 추가
AUTH_TOKEN_EXPIRED	401	JWT 만료	Firebase `getIdToken(true)` 재발급
AUTH_TOKEN_INVALID	401	JWT 서명 불일치	토큰 디코드 후 `iss/aud` 확인
AUTH_CSRF_MISMATCH	403	X-CSRF-Token 쿠키 미러 실패	쿠키 `__scms_csrf` 값과 헤더 일치 확인
AUTH_FORBIDDEN	403	권한 부족 (admin/installer 등)	관리자에게 그룹 변경 요청
AUTH_USER_SUSPENDED	403	사용자 status='suspended'	관리자 승인 대기

Project & Data (2xxx)

Code	HTTP	원인	해결
PROJECT_NOT_FOUND	404	존재하지 않거나 권한 없음	id 확인, 그룹 공유 여부 확인
PROJECT_LIMIT_EXCEEDED	403	플랜별 호선 한도 초과	tier 업그레이드
PROJECT_CONFLICT	409	CAS — 다른 사용자 동시 편집	새로고침 후 재시도, `serverUpdatedAt` 사용
PROJECT_PAYLOAD_TOO_LARGE	413	R2 바인딩 없이 800KB+ 시도	관리자에 R2 활성화 요청
CABLE_INVALID_DATA	400	필수 필드 누락 (name/type)	스키마 확인 (Cable schema)

Routing Engine (3xxx)

Code	HTTP	원인	해결
ROUTE_NO_PATH	200 (warn)	그래프상 경로 없음	노드 연결 / fromNode/toNode 확인
ROUTE_DUPLICATE_NODE	200 (warn)	경로에 중복 노드	cycle 검출, 그래프 정리
ROUTE_BLOCKED_BY_RULE	200 (warn)	선급 규칙 위반	FailedRoutes 패널 검토
ROUTE_TIMEOUT	504	15초 초과	케이블 분할 또는 worker 추가

Rate Limit & Quota (4xxx)

Code	HTTP	원인	해결
RATE_LIMITED	429	분당 요청 한도 초과	`X-RateLimit-Reset` 까지 대기
QUOTA_EXCEEDED	403	월간 API 콜 한도 초과	tier 업그레이드 / 다음 달 자동 리셋

AI & Integration (5xxx)

Code	HTTP	원인	해결
AI_KEY_EXHAUSTED	503	4 키 모두 소진	1분 후 재시도
AI_MODEL_UNAVAILABLE	502	Groq 장애	fallback 모델 자동 시도, 30초 후 재시도

Server (5xxx)

Code	HTTP	원인	해결
D1_QUERY_FAILED	500	D1 SQL 오류	요청 ID로 admin 문의 ([email protected])
R2_FETCH_FAILED	500	R2 hydrate 실패	15초 후 재시도, 지속 시 admin 문의
INTERNAL_ERROR	500	예상치 못한 오류	요청 ID + Time UTC로 admin 문의

대화창: 관리자 문의 · 메일: [email protected]