참고 / 오류
참고 / errors
오류
모든 통로에서 같은 오류 모양. 세부 코드와 큰 분류.
수정 2026년 11월 20일편집 docs seed버전 4
REST, MCP, 도구(callTool), CLI 모두 같은 모양으로 돌려줘요.
{ "error": "conflict_version", "kind": "conflict", "message": "…", "params": { "expected": 3, "current": 4 } }error는 세부 코드, kind는 큰 분류예요. 검증 오류에는 diagnostics(모든 문제를 한 번에)가, 충돌에는 current(상대 내용)가 더 붙어요.
분류#
not_found:not_found,version_not_found,key_not_found,route_not_foundunauthorized:unauthorized,invalid_key,key_expired,preview_invalid,preview_expiredforbidden:forbidden_read,forbidden_write,forbidden_publish,forbidden_keys,key_too_wide,cross_site등invalid:invalid_slug,invalid_title,invalid_field,slug_locked,schema_outdated등conflict:conflict_version,slug_takenprecondition:precondition_required(requireIfMatch를 켰을 때 428)
미디어 라이브러리가 있으면 파일 오류가 더해져요.
not_found:asset_not_found,unknown_store,unknown_image_sizeforbidden:forbidden_mediainvalid:asset_type_not_allowed,asset_type_mismatch(내용이 확장자와 달라요),asset_too_large(413),upload_incomplete,asset_rejected(media.scan이 거절했어요),asset_replace_type(같은 형식의 파일로만 바꿀 수 있어요),import_blocked,import_failed,invalid_folder,media_disabledconflict:asset_in_use(current에 문서 목록이 와요),folder_not_empty
전체 목록은 @mainsoft/agent-cms/errors의 ERROR_CODES에 있어요.
문구#
오류 문구는 영어가 기본이에요. createCms에 @mainsoft/agent-cms/messages/ko의 messages: ko를 주면 한국어가 돼요.