ZUKU API — 오류 · 응답 봉투

> 브랜드: ZUKU API

> 구현 기준: backend/rs/src/router.rs (envelope_ok / envelope_err / format_response), upload.rs

> 클라이언트의 ApiFailure(code, message, status) 패턴과 맞춘다.

---

응답 봉투 (Envelope)

모든 JSON API 응답은 공통 봉투를 사용한다 (models.rs · ApiMeta / ApiError).

성공

{
  "success": true,
  "data": { },
  "meta": {
    "request_id": "…",
    "timestamp": "2026-08-22T00:00:00Z",
    "version": "v1"
  }
}

• data: 엔드포인트별 페이로드
• meta.version: 현재 고정 "v1" (URL /api/v1 · 헤더 X-API-Version과 동일 세대)

실패

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "입력값을 확인해 주세요",
    "details": [
      { "field": "title", "message": "제목은 1~100자여야 합니다" }
    ]
  },
  "meta": {
    "request_id": "…",
    "timestamp": "…",
    "version": "v1"
  }
}

• details는 필드 단위 검증이 있을 때만 포함 (envelope_err_details)
• 단순 실패는 code + message만 (envelope_err)

예외

---

HTTP 상태 코드 (구현에서 쓰는 범위)

---

에러 코드 목록

router.rs / upload.rs에서 envelope_err · envelope_err_details · json_not_found로 실제로 나가는 코드다. (모듈 위임 moderation/analytics의 동일 코드 포함 가능)

인증 · 권한

검증 · 요청 형식

회원가입 · 계정

캡차

리소스 Not Found (세분화)

미디어 · Jump

인프라 · 기타

> 프론트 ApiFailure는 봉투 파싱 실패 시 INVALID_RESPONSE, 빈 본문 오류 시 HTTP_ERROR를 클라이언트 측에서 만들 수 있다. 이는 서버 envelope_err 코드가 아니다.

---

details[] 필드 오류

VALIDATION_ERROR 등에서:

"details": [
  { "field": "title", "message": "제목은 1~100자여야 합니다" },
  { "field": "tags", "message": "태그는 최대 10개입니다" }
]

콘텐츠 생성 시 흔한 field 값: title, description, tags, age_rating, type.

UI는 details를 필드별 인라인 에러로 매핑하고, 없으면 error.message를 토스트/배너로 쓴다.

---

응답 헤더

format_response가 모든 응답에 붙인다.

> 현재 백엔드는 Rate Limit을 강제하지 않는다. 헤더는 계약 자리표시자(dummy)다. 클라이언트가 Remaining으로 UX를 잠그면 안 된다.

그 외: Access-Control-Allow-Origin: *, 허용 메서드/헤더(Authorization, Content-Type) 등.

---

처리 팁 (JS / ApiFailure 스타일)

class ApiFailure extends Error {
  constructor(
    public code: string,
    message: string,
    public status: number,
    public details?: { field: string; message: string }[],
  ) {
    super(message);
    this.name = 'ApiFailure';
  }
}

async function apiFetch<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`/api/v1${path}`, {
    ...init,
    headers: {
      'Content-Type': 'application/json',
      ...(init?.headers ?? {}),
    },
  });

  if (res.status === 204) return undefined as T;

  const envelope = await res.json();
  if (!envelope.success) {
    throw new ApiFailure(
      envelope.error.code,
      envelope.error.message,
      res.status,
      envelope.error.details,
    );
  }
  return envelope.data as T;
}

// 사용 예
try {
  await apiFetch('/contents', { method: 'POST', body: JSON.stringify(payload), headers: {
    Authorization: `Bearer ${token}`,
  }});
} catch (e) {
  if (e instanceof ApiFailure) {
    switch (e.code) {
      case 'UNAUTHORIZED':
        // 로그인 유도
        break;
      case 'VALIDATION_ERROR':
        // e.details 로 폼 하이라이트
        break;
      case 'EMAIL_EXISTS':
      case 'HANDLE_EXISTS':
        // 가입 폼 전용 메시지
        break;
      case 'CAPTCHA_FAILED':
        // 캡차 재시도
        break;
      case 'DB_UNAVAILABLE':
      case 'INTERNAL_ERROR':
        // 잠시 후 재시도
        break;
      default:
        console.error(e.code, e.message, e.status);
    }
  }
}

---

관련 페이지

• contents.md
• media.md
• changelog.md — meta.version · X-API-Version