Video API (v1 구현 기준)¶
요약
영상(방문·점령) 도메인, base /api/videos, 전 엔드포인트 인증 필요.
업로드 흐름: presigned URL 발급 → 클라이언트 S3 직접 업로드 → 메타 저장(POST /api/videos, 이때 격자 점령).
확정은 파일 앞 4KB를 읽어 영상 컨테이너인지 확인하고 아니면 거부한다(3428 NOT_A_VIDEO_FILE, MSG-392).
교체는 같은 격자 안에서만(3422 GRID_MISMATCH), 내 영상이 0개 되면 점령 롤백.
이 노트로 답할 수 있는 질문¶
- 영상 업로드는 어떤 흐름으로 이루어지나?
- 업로드 메타 저장에 어떤 필드를 보내고 응답에 뭐가 오나?
- 영상 교체 시 좌표를 생략하면/보내면 어떻게 동작하나?
- 영상을 모두 삭제하면 격자 점령은 어떻게 되나?
- 영상 길이·확장자 제한은?
- 영상이 아닌 파일을 올리면 어떻게 되나?
- Video 도메인 에러 코드(3xxx)는 뭐가 있나?
엔드포인트¶
| 메서드/경로 | 핵심 |
|---|---|
POST /api/videos/presigned-url |
extension(mp4/mov)·contentType·contentLength → uploadUrl·s3Key·expiresInSec |
POST /api/videos |
s3Key·lat·lng·durationSec(1~30)·recordedAt → videoId·gridId·processingStatus·occupied(첫 점령 여부) |
PUT /api/videos/{videoId} |
본인만. 좌표 생략=파일만 교체, 좌표 지정=같은 격자 검사(다르면 3422). 교체 후 상태 UPLOADED(재인코딩) |
DELETE /api/videos/{videoId} |
본인만. 격자 내 영상 0개 되면 점령 롤백. 시간 제한 없음 |
에러 코드 (3xxx)¶
2026-08-24 코드(VideoErrorCode) 기준 전량이다. 이전 판은 3400·3401·3402·3403·3404·3413·3415·3422 여덟 개만 실려 있었다.
3400 INVALID_COORDINATE · 3401 INVALID_S3_KEY · 3402 UPLOAD_NOT_FOUND · 3403 VIDEO_FORBIDDEN · 3404 VIDEO_NOT_FOUND · 3409 ALREADY_IN_TARGET_STATUS · 3413 FILE_TOO_LARGE · 3415 UNSUPPORTED_EXTENSION · 3420 INVALID_VISIBILITY · 3422 GRID_MISMATCH · 3423 INVALID_CURSOR · 3424 RECORDED_AT_IN_FUTURE · 3425 HIGHLIGHT_SOURCE_TOO_LONG · 3426 HIGHLIGHT_SOURCE_UNREADABLE · 3427 EVENT_VIDEO_VISIBILITY_FIXED · 3428 NOT_A_VIDEO_FILE · 3429 HIGHLIGHT_BUSY · 3502 HIGHLIGHT_UPSTREAM_ERROR
3428 NOT_A_VIDEO_FILE (MSG-392, 2026-08-24)¶
업로드 확정이 S3 객체 앞 4KB를 읽어 영상 컨테이너 구조인지 보고, 아니면 400으로 거부한다. 그전에는 객체가 있는지와 크기가 상한 이내인지만 봐서, 이름만 .mp4인 1바이트 파일로 격자를 점령하고 뱃지·스트릭·미션 스탬프까지 받을 수 있었다.
- 3415 UNSUPPORTED_EXTENSION과 발생 시점이 다르다. 3415는 presigned URL 발급 단계에서 클라이언트가 선언한 확장자와 Content-Type을 보고, 3428은 확정 단계에서 실제 파일 내용을 본다.
- 사용자가 실제로 마주칠 상황은 업로드가 중간에 끊겨 앞부분만 올라간 경우라, FE 대응은 재업로드 유도다.
- 나가는 경로는 일반 업로드(
POST /api/videos) · 교체(PUT /api/videos/{videoId}) · 행사 업로드 셋이다. 미션 업로드(POST /api/missions/{missionId}/videos)에서는 관찰되지 않는다 — 미션 경로가 영상 도메인 실패를 전부 12409 MISSION_UPLOAD_UNAVAILABLE로 감싸는 기존 존재 은닉 계약(MSG-459) 때문이고, 이 티켓은 그 계약을 바꾸지 않았다. - 완결된 mp4 헤더를 붙인 파일은 통과한다(의도된 한계). 구조만 보고 재생 가능성은 판정하지 않으며, 그건 종전대로 인코딩 단계가 걸러 FAILED로 남긴다.