오류 응답 형식
작업이 실패한 경우 (status: "failed"), 응답에는 error 객체가 포함됩니다:
| 필드 | 유형 | 설명 |
|---|---|---|
error.code | string | 오류 코드 식별자. 아래 전체 목록 참조 |
error.message | string | 사용자 친화적인 오류 설명 및 문제 해결 팁 |
오류 코드 개요
클라이언트 오류 (사용자가 수정 가능)
클라이언트 오류 (사용자가 수정 가능)
| 오류 코드 | 설명 | 재시도 |
|---|---|---|
content_policy_violation | 콘텐츠가 안전 정책 위반 | 콘텐츠 수정 후 재시도 |
invalid_parameters | 잘못된 요청 매개변수 | 매개변수 수정 후 재시도 |
image_processing_error | 이미지 처리 실패 | 다른 이미지 사용 |
image_dimension_mismatch | 이미지 크기가 요청과 불일치 | 이미지 크기 조정 후 재시도 |
request_cancelled | 요청이 취소됨 | 재제출 |
서버 오류 (나중에 재시도)
서버 오류 (나중에 재시도)
오류 코드 세부 사항
content_policy_violation
콘텐츠 정책 위반
요청이 안전 필터에 의해 차단되었습니다. 이것은 가장 일반적인 오류 유형으로 다음 시나리오를 포함합니다:
| 하위 유형 | 설명 | 메시지 예시 |
|---|---|---|
| 사실적 인물 | 업로드된 이미지에 실제 사람 얼굴 포함 | photorealistic people detected |
| 유명인 초상 | 유명인 또는 공인 관련 | celebrity detected in image |
| 저작권/상표 | 브랜드 로고, 상표 또는 저작권 보호 IP 관련 | third-party content violation |
| 성인/NSFW | 누드 또는 성적 암시 콘텐츠 포함 | nudity detected |
| 폭력/자해 | 폭력적, 노골적 또는 자해 콘텐츠 포함 | violence content blocked |
| 미성년자 보호 | 미성년자 관련 민감한 콘텐츠 | minor content not allowed |
| 일반 정책 | 기타 콘텐츠 정책 위반 | content policy violation |
generation_failed_no_content
생성 실패
모델이 요청에 대한 출력을 생성할 수 없었습니다. 요청 형식은 유효했지만 처리 중에 모델이 결과를 생성하지 못했습니다.
- 프롬프트 품질 부족: 설명이 너무 모호하거나 모순되어 모델이 이해할 수 없음
- 모델 능력 한계: 프롬프트가 모델의 생성 능력을 초과
- 업스트림 서비스 문제: 기본 모델 서비스가 빈 결과를 반환
- 보호된 콘텐츠 감지: 프롬프트 또는 참조 이미지에 워터마크 제거 또는 보호된 콘텐츠(로고, 상표 등)가 포함될 수 있음
invalid_parameters
잘못된 매개변수
요청 매개변수가 모델 요구사항을 충족하지 않습니다.
| 하위 유형 | 설명 | 예시 |
|---|---|---|
| 프롬프트가 너무 긺 | 프롬프트가 모델의 최대 길이 초과 | Prompt is too long |
| 이미지 크기 | 이미지 너비/높이 또는 화면 비율이 범위 밖 | image dimensions must be between 240 and 7680 |
| 파일이 너무 큼 | 업로드 파일이 크기 제한 초과 | file size exceeds 10MB |
| 지원되지 않는 형식 | 업로드 파일 형식이 지원되지 않음 | unsupported file type |
| 비디오 길이 | 비디오 길이가 모델의 지원 범위 밖 | Video duration must be between 1-30 seconds |
image_processing_error
이미지 처리 실패
시스템이 입력 이미지를 처리할 수 없었습니다.
- 이미지 URL에 접근할 수 없음 (인증 필요, CDN 제한, 만료된 링크)
- 이미지 형식이 지원되지 않음 (예: HEIC, AVIF)
- 이미지 파일 손상
- 네트워크 문제로 이미지 다운로드 실패
image_dimension_mismatch
이미지 크기 불일치
입력 이미지의 크기가 요청에 지정된 크기와 일치하지 않습니다. 이미지에서 비디오로 변환하는 시나리오에서 흔히 발생합니다.
aspect_ratio=1280x720(16:9) 시 1280x720 가로 이미지 필요aspect_ratio=720x1280(9:16) 시 720x1280 세로 이미지 필요
service_error
서비스 오류
업스트림 서비스에서 내부 문제가 발생했습니다. 일반적으로 일시적이며 시스템이 자동으로 다른 사용 가능한 경로로 전환합니다.
- 업스트림 모델 서비스 일시적 사용 불가
- 서버 과부하 / 높은 트래픽
- 유지보수 진행 중
- 네트워크 연결 중단
generation_timeout
생성 시간 초과
작업이 허용된 시간 내에 완료되지 않았습니다.
- 시스템 부하가 높아 대기열 지연 발생
- 작업 복잡성이 높음 (고해상도, 긴 비디오 등)
- 업스트림 서비스 응답이 느림
quota_exceeded
할당량 / 속도 제한 초과
요청 빈도 또는 동시성 제한을 초과했습니다.
- 짧은 시간에 너무 많은 요청 전송 (속도 제한)
- 여러 작업이 동시에 처리 중 (동시성 제한)
- 계정 할당량 고갈
resource_exhausted
리소스 고갈
업스트림 서비스의 컴퓨팅 리소스가 일시적으로 고갈되었습니다. 일반적으로 모델 사용 피크 기간에 발생합니다.
resource_not_found
리소스를 찾을 수 없음
요청한 작업 ID가 존재하지 않거나 만료되었습니다.
request_cancelled
요청 취소됨
작업이 처리 중에 취소되거나 중단되었습니다.
service_unavailable
서비스 사용 불가
내부 인증 또는 연결 문제가 발생했습니다. 이 오류는 자동으로 기록되며 일반적으로 빠르게 해결됩니다.
unknown_error
알 수 없는 오류
분류되지 않은 오류. 시스템이 특정 오류 유형을 식별할 수 없었습니다.
모범 사례
오류 처리 예시
재시도 가능 vs 재시도 불가
요청 수정 후 재시도
content_policy_violation— 콘텐츠 수정invalid_parameters— 매개변수 수정image_processing_error— 다른 이미지 사용image_dimension_mismatch— 이미지 크기 조정
직접 재시도 가능
generation_failed_no_content— 다른 프롬프트로 재시도service_error— 대기 후 재시도generation_timeout— 대기 후 재시도resource_exhausted— 자동 복구quota_exceeded— 빈도 줄이고 재시도