문서

오류 처리 / 호출 비율 제한

오류 처리

API 요청 처리 중 오류가 발생하면 HTTP 상태 코드와 함께 오류 정보 객체(error)가 전달되며 해당 객체에는 오류 코드(code)와 에러 메시지(message)가 들어 있습니다. 작업 생성이 성공적으로 접수된 후에도 실제 비디오 생성 과정에서 실패가 발생할 수 있으므로, 주기적으로 조회하거나 실패 콜백 처리를 구현해 두어야 합니다.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

HTTP	필드	해결 방법
400	`invalid_request`	전송한 JSON 형식의 결함 여부, 프롬프트 누락, 파라미터 값의 유효 범위를 확인하거나 미디어 파일의 HTTPS 다운로드 주소가 정상인지 확인 후 다시 시도하세요.
401	`invalid_api_key`	전달된 Bearer 토큰 및 API 키가 활성화 상태인지 확인해 주세요.
402	`insufficient_credits`	계정에 크레딧을 추가로 충전하거나, 생성 사양을 낮추어 예상 작업 크레딧 소비량을 감축하십시오. 응답 메시지에 필요한 금액과 현재 잔액이 포함되어 안내될 수 있습니다.
403	`forbidden`	오류 메시지에 안내된 계정 수준의 제한 사항을 확인해 주세요.
404	`not_found`	검색에 사용한 작업 ID를 다시 확인해 주세요. 요청한 API 키를 소유한 유저가 생성한 작업만 조회가 가능합니다.
429	`rate_limited`	응답 헤더로 전달된 Retry-After 지정 시간만큼 일시 정지 후 다시 전송을 시도해 주세요.
500	`internal_error`	반환된 에러 메시지 및 API 세부 로그를 자세히 살펴보세요. 동일 요청 재시도 시 불필요하게 가예약 및 청구 처리가 중복 발생할 위험이 있으므로 재시도 시 주의해 주십시오.

호출 비율 제한

태스크 생성: API 키당 기본적으로 분당 최대 100회의 요청이 허용됩니다. 현재 맞춤형 속도 제한은 제공되지 않습니다.

태스크 조회: API 키당 기본적으로 분당 최대 120회의 요청이 허용됩니다. 조회 요청과 태스크 생성 요청은 각각 별도로 계산됩니다.

이미지 및 비디오 생성 요청은 동일한 API 키 속도 제한을 공유합니다.

호출 초과 발생 시(HTTP 429), 작업 생성은 Retry-After: 60을 헤더로 받으며 조회 요청은 Retry-After: 5를 응답 헤더로 받습니다. 지수 백오프 전략을 채택하고 과도하게 빈번한 폴링은 자제해 주세요.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}