오류 및 제한
VideoUpscaler API의 오류 형식, 상태 코드, 요청 제한, 재시도 가이드입니다.
오류 형식
모든 오류는 같은 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 | 동영상이 600초를 초과함 | 아니요 |
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회 |
| 동영상 길이 | 600초 |
원격 video_url 크기 | 500MB |
| 업로드 파일 크기 | 100MB |
| 업로드 URL 유효 기간 | 1시간 |
| 활성 API 키 | 계정당 20개 |
안전하게 재시도하기
/upscale에는 항상 Idempotency-Key를 보내세요. 요청이 타임아웃되거나 500 또는 504를 받으면 같은 키로 재시도하세요. 두 번 차감되는 대신 이미 생성된 작업을 받게 됩니다.
502 upstream_error는 다릅니다. 작업은 생성됐지만 시작에 실패해 환불되었으므로, 같은 키로는 실패한 작업만 계속 반환됩니다. 새 키로 재시도하세요.