오류

오류 응답 형식

대부분의 4xx / 5xx 응답은 같은 형식을 따릅니다.

{
  "detail": "human-readable message",
  "code": "optional.stable.code"
}

detail은 사람이 읽을 수 있는 설명입니다. 이 형식에서는 항상 문자열입니다.
code는 no_valid_urls, quota_exceeded_videos처럼 기계가 읽을 수 있는 고정된 사유 코드입니다. 실패에 고정된 사유가 있을 때만 포함되고, 그 외에는 없거나 null입니다. 항상 있다고 가정하지 말고 존재 여부로 분기하세요.

다음 세 가지 경우는 이 형식을 그대로 따르지 않습니다. detail을 읽기 전에 타입을 먼저 확인하세요.

스키마 검증 실패는 FastAPI의 배열 형식으로 반환됩니다(다음 섹션 참고).
게이트웨이가 해석할 수 없는 하위 서비스의 오류 본문은 다시 쓰지 않고 그대로 전달됩니다.
엣지 프록시처럼 API 바깥에서 발생한 오류는 형식 없이 불투명한 본문으로 올 수 있습니다.

검증 오류(422 배열 형식)

스키마 검증에서 거부된 요청은 FastAPI의 목록 형식으로 반환됩니다. 이때 detail은 문자열이 아니라 필드 오류의 배열입니다.

{
  "detail": [
    {
      "loc": ["body", "url"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

요청 본문을 받는 모든 엔드포인트가 이 형식을 반환할 수 있습니다. 흔한 예는 POST /api/v1/videos/batch에 허용 길이를 넘는 items 배열을 보내는 경우입니다.

노트

422가 항상 배열 형식인 것은 아닙니다. 일부 라우트는 문자열 형식과 code를 담은 자체 422를 반환합니다. 예를 들어 POST /api/v1/videos/batch/upload-sheet에 지원하지 않는 파일 형식이나 url 열이 없는 시트를 보내는 경우입니다. typeof detail로 분기하면 두 경우를 모두 처리할 수 있습니다.

특수 코드

`upstream_error_too_large`

이 code는 실패한 서비스가 아니라 게이트웨이가 직접 만듭니다. 하위 서비스의 오류 본문이 너무 커서 전달할 수 없었다는 뜻입니다. HTTP 상태 코드는 유지되지만 항목별 사유는 사라집니다. 상세 응답을 받으려면 항목 수를 줄여 재시도하세요.

시트 업로드의 `rejected`

POST /api/v1/videos/batch/upload-sheet의 시트 파싱 실패(413, 422)에서 code가 no_valid_urls이면 형제 키 rejected가 하나 더 붙습니다. 시트를 파싱하면서 제외된 행의 수입니다. 이 행들은 어떤 배치에도 기록되지 않았습니다.

{
  "detail": "No valid URL rows found in the sheet",
  "code": "no_valid_urls",
  "rejected": 12
}

작업 실패는 HTTP 오류가 아닙니다

색인 생성에 실패한 영상도 GET /api/v1/jobs/{job_id}에서 200을 반환합니다. 실패 정보는 본문에 status: "failed", 고정된 reason_code, 원본 error 텍스트로 담깁니다. HTTP 상태가 아니라 reason_code로 분기하세요.

HTTP 상태 코드

HTTP	의미	처리 방법
`401`	API 키가 없거나 유효하지 않습니다.	`Authorization: Bearer ...` 헤더를 확인하세요. 인증을 참고하세요.
`403`	공개 API 루트(`/api/v1`, `/api/v1.1`) 밖에서 키를 사용했습니다.	API 키로는 대시보드 라우트에 접근할 수 없습니다. 인증을 참고하세요.
`404`	참조한 영상, 작업 또는 광고를 찾을 수 없습니다.	오타이거나 다른 조직의 리소스입니다. `GET /api/v1/usage`는 조직에 사용 한도 플랜이 아직 없을 때도 `404`를 반환합니다.
`409`	광고가 준비되지 않았습니다.	`ad_id`는 있지만 `status`가 `ready`가 아닙니다(아직 `resolving`이거나 `failed`). `GET /api/v1/ads/{ad_id}`를 폴링하고 `ready`가 되면 재시도하세요.
`413`	업로드가 너무 큽니다.	시트 업로드에서 파일이 10 MB 제한을 넘거나, 유효한 URL 행이 한 배치의 허용 개수(현재 500)보다 많습니다. 여러 시트로 나누세요.
`422`	요청 본문이 검증에 실패했습니다.	요청을 수정하세요. `detail`에 문제 필드가 표시되거나(배열 형식) `code`가 담깁니다(기본 형식).
`500`	상위 서비스 오류입니다.	대체로 재시도해도 안전합니다. 파일 업로드라면 먼저 배치나 영상을 확인하세요. 사용량과 한도를 참고하세요.
`503`	사용 한도 저장소를 일시적으로 사용할 수 없습니다.	`GET /api/v1/usage`에서 반환됩니다. 재시도하세요.

재시도 가이드

500 은 대체로 재시도해도 안전합니다. 게이트웨이가 상위 서비스의 실패를 전달한 것이며 요청 자체는 대부분 문제없습니다. 예외는 중복 제거 키가 없는 파일 업로드입니다. 다시 보내기 전에 배치나 영상을 조회하세요.
GET /api/v1/usage의 503 은 일시적입니다. 재시도하세요.
409 는 광고 확인이 끝나면 저절로 해소됩니다. 검수 요청을 무작정 다시 보내지 말고 광고를 폴링하세요.
upstream_error_too_large 는 요청이 영구적으로 실패했다는 뜻이 아니라 오류 경로에 비해 요청이 너무 컸다는 뜻입니다. 항목 수를 줄여 재시도하세요.
위에 없는 4xx 는 재시도해도 결과가 바뀌지 않습니다. 요청을 수정하세요.

팁

POST /api/v1/videos는 아직 색인 생성 중인 URL에 대해 멱등합니다. 다시 보내면 기존 video_id / job_id가 created: false와 함께 반환되므로, 네트워크 오류 후 재시도해도 파이프라인이 중복으로 시작되지 않습니다.

오류 응답 형식​

검증 오류(422 배열 형식)​

특수 코드​

upstream_error_too_large​

시트 업로드의 rejected​

작업 실패는 HTTP 오류가 아닙니다​

HTTP 상태 코드​

재시도 가이드​