크리에이터 오류 코드

크리에이터 앱은 로케일이 4종(ko·en·vi·jp)인데, 서버 오류 메시지는 한국어뿐이었습니다. 일본·미국·베트남 크리에이터는 무엇이 잘못됐는지 읽을 수 없었습니다. 이 문서는 그 문구를 프론트에서 로케일별로 고를 수 있도록, 서버가 내려주는 code 의 전체 사전을 정리한 것입니다.

오류 응답 형태

{
  "status": 400,
  "code": "EXPLANATION_ATTACHMENT_TOO_MANY",
  "message": "첨부는 최대 5개까지 등록할 수 있습니다. 현재 7개입니다.",
  "args": { "max": 5, "current": 7 },
  "data": null
}

코드 규격

1. code 는 서버 enum 의 상수명과 항상 같다. 별도 코드 문자열을 두지 않으므로 중복이 생길 수 없다.
2. 번호를 쓰지 않는다. CONTRACT_003 같은 값은 뜻을 읽을 수 없어 폐기했다.
3. 형태는 도메인_대상_사유 의 대문자 스네이크다. 끝의 사유가 HTTP 상태를 결정한다.
4. 문장에 들어갈 값은 문장에 박지 않고 args 슬롯으로 뺀다.

표 밖의 예외는 둘뿐이고, 둘 다 도메인이 상태를 정합니다.

• AUTH_TOKEN_* · AUTH_REFRESH_TOKEN_* 은 접미사와 무관하게 401 입니다.
• 공통 인프라 코드(INTERNAL_SERVER_ERROR · DATABASE_ERROR · DB_LOCK_ERROR · CACHE_ERROR · VALIDATION_ERROR · MALFORMED_REQUEST_BODY)는 기존 코드 문자열을 물려받은 고정 값입니다.
• 레거시 호환 코드 — INVALID_INFLUENCE_USER(404) · DUPLICATE_PORTFOLIO(409) · CONTACT_VERIFICATION_REQUIRED(403) · CONTRACT_INVALID_STATE(400) · CONTRACT_OTP_RATE_LIMIT(429) · INVALID_SNS_URL(400) · PYTHON_SERVER_ERROR(500) · TOKEN_INVALID(401) · REFRESH_TOKEN_EXPIRED(401) · SCRIPT_PDF_IMPORT_FAILED(502) · SERVER_ERROR(500) · ACCOUNT_WITHDRAWN(401). 이름이 규칙을 따르지 않지만 프론트가 이미 이 이름으로 분기하고 있어 보존합니다.

프론트 적용 방법

프론트(glowb-frontend)는 앱 공용 오류 사전과 번역 단계를 이미 갖추고 있습니다. 새 코드가 생기면 사전에 키만 추가하면 됩니다.

• 사전 위치: packages/ui/src/lib/api-errors/{ko,en,jp,vi}.json. 키는 서버 code 그대로, 값은 로케일 문구입니다. 슬롯은 서버 args 키와 같은 이름을 씁니다.
• 번역 단계: 크리에이터 apps/glowb-ai-creator/apis/index.ts 와 광고주·에이전시 packages/corp-shared/src/http.ts 가 오류 응답을 localizeApiResponse 로 통과시켜 message 를 로케일 문구로 바꿉니다. 서버 원문은 rawMessage 에 남습니다.
• 로케일 판정: URL 첫 경로(/en/…) → <html lang> → NEXT_LOCALE 쿠키 → 브라우저 언어 → ko 순입니다.
• 폴백: 사전에 없는 코드이거나 슬롯 값이 빠지면 서버 message(한국어)를 그대로 씁니다. 그래서 서버에 새 코드가 먼저 배포돼도 화면이 비지 않고, 사전 키가 추가되면 그때부터 번역됩니다.

{
  "SUBMISSION_ITEMS_EMPTY": "There is nothing to submit.",
  "EXPLANATION_ATTACHMENT_TOO_MANY": "Up to {max} attachments allowed. You have {current}.",
  "REQUEST_ARGUMENT_INVALID": "Invalid request value. ({reason})"
}

입력값 검증 오류

@Valid 실패는 코드가 항상 VALIDATION_ERROR 하나입니다. 어느 필드가 무엇을 어겼는지는 args.errors 에 실립니다.

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "받는 사람은 필수입니다, 기본 주소는 필수입니다",
  "args": {
    "errors": [
      { "field": "recipientName", "code": "VALIDATION_REQUIRED", "message": "받는 사람은 필수입니다" },
      { "field": "baseAddress",   "code": "VALIDATION_REQUIRED", "message": "기본 주소는 필수입니다" }
    ]
  }
}

필드별 코드는 어긴 제약이 무엇인지를 가리킵니다. field 와 조합하면 한국어 문장 없이도 문구를 만들 수 있습니다.

코드 사전

전체 175개입니다. 슬롯 열이 있는 코드는 args 가 함께 내려옵니다.

공통

모든 크리에이터 엔드포인트에서 나올 수 있다. GlobalExceptionHandler 가 채운다.

인증·인가

AUTH_TOKEN_* 과 AUTH_FORBIDDEN 은 시큐리티 필터 단계에서 나가므로 봉투가 다르다(아래 “아직 규격 밖인 구간” 참고).

크리에이터 계정

연락처 인증

CONTACT_VERIFICATION_EMAIL_BOUNCED 는 프론트가 이미 분기에 쓰고 있어 이름을 바꾸지 않는다.

캠페인

캠페인 지원

단가 협상

제공 옵션

제출물

검수 피드백

AI 검수

스크립트 PDF 가져오기

최종 제작물

소명

제출 링크(무인증)

로그인 없이 열리는 매직링크 화면이라, 로케일을 URL 이나 브라우저 설정에서 잡아야 한다.

DM_LINK

배송지

전자계약

가이드라인 조회

Instagram 연동

포트폴리오

알림

AFFILIATE

파일 업로드

변경 이력

2026-10-08 — 공통 처리기 정리

아직 규격 밖인 구간

아래는 이 사전을 그대로 쓸 수 없는 경로입니다. 프론트는 당분간 예외 처리가 필요합니다.