VideoUpscaler API의 오류 형식, 상태 코드, 요청 제한, 재시도 가이드입니다. 오류 응답의 JSON 구조와 code 값의 의미, 그리고 Idempotency-Key로 업스케일 요청을 중복 과금 없이 안전하게 재시도하는 방법을 설명합니다.

오류 형식

모든 오류는 같은 JSON 구조를 가집니다. 코드에서는 code를 사용하세요. message는 사람이 읽기 위한 것이며 변경될 수 있습니다.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this video. Buy credits to continue."
  }
}

상태 코드

상태	코드	의미	재시도 여부
`400`	`invalid_request`	요청 형식이 잘못됨	아니요 — 요청을 수정하세요
`401`	`unauthorized`	API 키가 없거나 유효하지 않음	아니요
`402`	`insufficient_credits`	크레딧 부족	크레딧 구매 후
`403`	`paid_plan_required`	계정이 크레딧을 구매하거나 구독한 적이 없음	크레딧 구매 후
`403`	`invalid_upload_token`	업로드 URL이 유효하지 않거나 만료됨	새 업로드 URL을 요청하세요
`403`	`invalid_stream_token`	이벤트 스트림 URL이 유효하지 않거나 만료됨	`/tasks/{id}/events`를 다시 여세요
`404`	`not_found`	계정에 해당 작업이 없음	아니요
`409`	`idempotency_conflict`	`Idempotency-Key`가 다른 파라미터로 재사용됨	새 키를 사용하세요
`411`	`invalid_request`	업로드 `PUT`에 본문이나 `Content-Length`가 없음	아니요 — 요청을 수정하세요
`413`	`file_too_large`	동영상이 크기 제한을 초과함	아니요
`422`	`video_fetch_failed`	`video_url`을 다운로드할 수 없음	URL 수정 후
`422`	`unsupported_video`	읽을 수 있는 MP4, MOV, WebM 파일이 아님	아니요
`422`	`video_too_long`	동영상이 해상도별 제한을 초과함	아니요
`422`	`video_not_found`	이 `video_url`에 업로드된 파일이 없음	업로드 완료 후
`429`	`rate_limited`	요청이 너무 많음	예, `Retry-After`초 후
`500`	`internal_error`	서버 측 오류 발생	예, 같은 `Idempotency-Key`로
`502`	`upstream_error`	처리를 시작할 수 없음. 차감된 크레딧은 환불됨	예, 새 `Idempotency-Key`로
`504`	`upstream_timeout`	`video_url` 다운로드 시간이 너무 오래 걸림	예, 또는 더 빠른 호스트를 사용하세요

제한

항목	값
요청 수	API 키당 분당 약 120회
동영상 길이	1080p 1200초, 2k·4k 600초
원격 `video_url` 크기	500MB
업로드 파일 크기	100MB
업로드 URL 유효 기간	1시간
활성 API 키	계정당 20개

안전하게 재시도하기

/upscale에는 항상 Idempotency-Key를 보내세요. 요청이 타임아웃되거나 500 또는 504를 받으면 같은 키로 재시도하세요. 두 번 차감되는 대신 이미 생성된 작업을 받게 됩니다.

502 upstream_error는 다릅니다. 작업은 생성됐지만 시작에 실패해 환불되었으므로, 같은 키로는 실패한 작업만 계속 반환됩니다. 새 키로 재시도하세요.

오류 및 제한

오류 형식

상태 코드

제한

안전하게 재시도하기

On this page