오류 응답 형식
작업이 실패한 경우 (status: "failed"), 응답에는 error 객체가 포함됩니다:
오류 코드 개요
클라이언트 오류 (사용자가 수정 가능)
클라이언트 오류 (사용자가 수정 가능)
오류 코드 세부 사항
content_policy_violation
콘텐츠 정책 위반
요청이 안전 필터에 의해 차단되었습니다. 이것은 가장 일반적인 오류 유형으로 다음 시나리오를 포함합니다:
generation_failed_no_content
생성 실패
모델이 요청에 대한 출력을 생성할 수 없었습니다. 요청 형식은 유효했지만 처리 중에 모델이 결과를 생성하지 못했습니다.
- 프롬프트 품질 부족: 설명이 너무 모호하거나 모순되어 모델이 이해할 수 없음
- 모델 능력 한계: 프롬프트가 모델의 생성 능력을 초과
- 업스트림 서비스 문제: 기본 모델 서비스가 빈 결과를 반환
- 보호된 콘텐츠 감지: 프롬프트 또는 참조 이미지에 워터마크 제거 또는 보호된 콘텐츠(로고, 상표 등)가 포함될 수 있음
invalid_parameters
잘못된 매개변수
요청 매개변수가 모델 요구사항을 충족하지 않습니다.
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— 빈도 줄이고 재시도