오류 처리

다시 보내기 전에 오류 형식과 요청 단계를 구분하기

모델 호출의 공통 오류는 최상위 type과 error_ref를 사용하지만 영상 작업과 파일 API는 error.code를 사용하기도 합니다. Batch의 업로드와 작업 제출에는 각각 다른 요청 키와 재시도 조건이 있습니다. 생성 요청이나 Batch 제출의 응답을 받지 못했다면 새 POST를 보내기 전에 영상 접수 여부 확인 또는 Batch의 원래 요청 확인을 따르세요. 같은 요청을 새로 실행하면 비용이 다시 발생할 수 있습니다.

오류 응답 구조

공통 모델 호출 오류는 다음 JSON 구조를 사용합니다. 작업 조회, 참조 파일 업로드와 파일 링크 발급에는 error.code를 사용하는 오류도 있으므로 작업 조회와 References, 파일 링크 발급의 응답 형식을 따릅니다.

{
  "type": "<에러 코드>",
  "title": "<짧은 제목>",
  "status": <HTTP 상태 코드>,
  "detail": "<원인을 설명하는 본문>",
  "error_ref": "<문의 시 전달할 식별자>"
}

오류 type별 대응

위 공통 형식으로 반환된 오류는 표에 없더라도 status와 type을 기준으로 처리하고, detail은 진단용으로만 사용합니다.

재시도할 수 있는 경우

영상 생성 POST의 응답이 유실되거나 제한시간을 넘기면 먼저 접수 여부를 확인합니다. 오류 코드만 보고 새 요청을 반복하면 영상이 중복 생성될 수 있습니다. 작업 ID를 받았다면 같은 작업을 조회하고, ID가 없다면 요청 시각과 스페이스 이름으로 문의합니다.

지원에 전달할 정보

재시도 후에도 같은 오류가 계속되면 렛서 플랫폼에 로그인한 뒤 플랫폼 내 문의 기능을 사용합니다. 요청 시각, 엔드포인트, HTTP 상태와 응답에 있는 type 또는 error.code, error_ref, 확보한 작업 ID를 남기고, API 키나 전체 인증 헤더는 보내지 않습니다.

비동기 영상 작업과 파일 오류

Seedance 영상 생성의 접수 오류, 작업 조회 오류와 파일 수령 오류는 각각 구분합니다. 작업 조회의 HTTP 503을 생성 실패로 처리하거나 새 생성 요청으로 자동 재시도하지 않습니다. 작업 ID를 받았다면 같은 작업을 조회합니다.

파일 준비 중에는 기다렸다가 같은 미디어 ID로 다시 확인합니다. 다운로드 링크 만료는 새 링크 발급으로 복구할 수 있지만 파일 보관 만료는 다릅니다. 발급 요청의 오류와 반환 링크를 열 때의 오류는 파일 링크 발급에서 각각 확인합니다.