오류와 지출
오류 봉투, 코드, 체리와 요청 한도입니다.오류 봉투
모든 오류 응답은 같은 모양이고, 응답 헤더
X-Request-Id가 본문의 requestId와 같습니다. 문의할 때 이 값을 함께 알려 주세요.오류 봉투 — json
message는 사람이 읽는 문장이고 바뀔 수 있습니다. 코드 분기는 error.code와 details로 하세요.코드와 상태
공개 REST가 쓰는 코드와 HTTP 상태입니다.
| 상태 | 코드 | 뜻 | 해야 할 일 |
|---|---|---|---|
| 400 | INVALID_INPUT | 본문이 틀림, 모르는 필드, 지원하지 않는 옵션 값, 견적이 maxCherry보다 큼, 멱등 키 헤더와 본문이 다름 | 메시지의 필드 경로와 가능한 값을 보고 고칩니다. |
| 401 | UNAUTHORIZED | 키가 틀림, 만료, 폐기, 권한 부족, 인증 헤더 두 개 | 새 키를 만들고 허용한 기능을 확인합니다. |
| 402 | INSUFFICIENT_CHERRY | 잔액 부족 | 충전한 뒤 같은 요청을 다시 보냅니다. |
| 403 | FORBIDDEN | 연령 확인 전, 또는 문서 편집 권한 없음(영상) | 앱에서 연령 확인을 마치거나 문서 권한을 받습니다. |
| 404 | NOT_FOUND | 없는 작업, 남의 작업, 접근할 수 없는 문서 | id와 계정을 확인합니다. |
| 409 | CONFLICT | 같은 멱등 키에 다른 본문, 이미 시작돼 취소할 수 없음, 종결된 요청의 키 재사용, 문서가 바뀜(영상) | details의 사유를 봅니다. |
| 422 | PRICE_UNPUBLISHED | 가격을 확정할 수 없는 영상 모델·옵션 조합 | 다른 모델이나 옵션을 고릅니다. |
| 429 | RATE_LIMITED | 호출 한도 또는 동시·시간당 접수 한도 | details.limit_kind를 보고 기다립니다. |
| 429 | SPEND_LIMIT_EXCEEDED | 키의 기간 지출 한도 초과 | 한도를 올리거나 다른 키를 쓰거나 리셋을 기다립니다. |
| 500 | INTERNAL | 서버 오류 | requestId와 함께 문의합니다. |
| 503 | UNAVAILABLE | 제공자나 환율이 지금 준비되지 않음 | 잠시 뒤 같은 요청을 다시 보냅니다. |
계약 코드 목록에는
POLICY_REACCEPTANCE_REQUIRED(409)도 있습니다. 결제 전 약관 재동의용이고 생성 경로는 이 코드를 내지 않습니다.세부 정보
details는 코드에 따라 다음 값을 담습니다.| 키 | 어떤 오류에 | 뜻 |
|---|---|---|
required_cherry, balance_cherry | 잔액 부족 | 필요한 체리와 지금 쓸 수 있는 체리 |
required_cherry | 400(상한 초과), 키 지출 한도 | 서버가 계산한 견적 |
limit_kind, retry_after_seconds | 속도 제한 | 걸린 한도와 기다릴 초 |
spend_limit_cherry, spent_cherry, spend_period, retry_after_seconds | 키 지출 한도 | 한도, 이 기간에 쓴 양, 기간(day, month), 리셋까지 남은 초 |
price_reason | 가격 미공표 | 가격을 확정하지 못한 사유 |
conflict_reason | 409 | idempotency_key_reused: 같은 키를 다른 본문에 씀 |
cancel_reason | 409 | already_started: 이미 시작돼 취소할 수 없음 |
limit_kind 값은 다음과 같습니다.| 값 | 뜻 | 기다리면 풀리나 |
|---|---|---|
surface_read, surface_write | 키의 시간당 읽기·쓰기 호출 한도 | 예. Retry-After 뒤 |
video_hourly | 영상 시간당 접수 한도(60) | 예 |
image_active, video_active, audio_active | 동시에 진행 중인 작업 수 한도 | 작업이 끝나면 풀립니다. 기다릴 초는 오지 않습니다 |
image_daily | 하루 이미지 접수 한도(10) | 다음 날 |
price_reason 값은 no_sku_published, token_rate_unpublished, megapixel_basis_required, sku_unrecognized, invalid_sku_value, no_matching_sku, ambiguous_input_pricing, invalid_axes입니다.접수 단계의 오류
| 상황 | 응답 | 해야 할 일 |
|---|---|---|
| 본문 필드가 틀림, 모르는 필드 | 400 INVALID_INPUT | 메시지의 필드 경로를 고칩니다. |
| 모델이 지원하지 않는 옵션 값 | 400 INVALID_INPUT | 메시지가 알려 주는 가능한 값 중에서 고릅니다. |
| 모르는 모델 id | 400 INVALID_INPUT | 모델 목록 경로로 id를 확인합니다. |
견적이 maxCherry보다 큼 | 400 INVALID_INPUT | required_cherry를 보고 상한을 올리거나 옵션을 줄입니다. |
| 이미지 가격이 확정되지 않는 조합 | 400 INVALID_INPUT | 다른 모델이나 옵션을 고릅니다. |
| 영상 가격이 확정되지 않는 조합 | 422 PRICE_UNPUBLISHED | price_reason을 보고 다른 모델이나 옵션을 고릅니다. |
| 허용되지 않는 프롬프트 | 400 INVALID_INPUT | 프롬프트를 고칩니다. 이 경우 체리는 쓰이지 않습니다. |
초안이 있는데 draftJobId 없이 본 생성 | 400 INVALID_INPUT | 메시지의 초안 작업 id를 draftJobId로 보냅니다. |
| 키가 틀림, 만료, 폐기, 권한 부족 | 401 UNAUTHORIZED | 새 키를 만들고 권한을 확인합니다. |
| 잔액 부족 | 402 INSUFFICIENT_CHERRY | 충전한 뒤 같은 요청을 다시 보냅니다. |
| 같은 키, 다른 본문 | 409 CONFLICT | 같은 요청이면 본문을 똑같이, 새 요청이면 새 키를 씁니다. |
| 동시 작업 한도 | 429 RATE_LIMITED | 진행 중인 작업이 끝난 뒤 같은 키로 다시 보냅니다. |
읽기 단계의 오류
없는 작업, 남의 작업은 모두 404입니다. 존재 여부를 구분해 알려 주지 않습니다. 목록의
limit이나 status가 틀리면 400입니다.작업이 실패로 끝날 때
접수가 202여도 작업은 실패할 수 있습니다. 조회 응답의 상태가
failed이면 이미지는 error, 영상과 오디오는 failure를 봅니다. 둘 다 code, message, retryable을 담습니다.| 종류 | code 값 |
|---|---|
| 이미지 | canceled, hold_pending, intent_exhausted, capability_unsupported, prompt_rejected, provider_failed, generation_failed, processing_timeout, render_interrupted, title_layer_not_transparent |
| 영상 | canceled, capability_unsupported, provider_rejected, provider_failed, provider_settlement_invalid, processing_timeout, result_ingest_failed, result_invalid, input_asset_unavailable, submit_interrupted, generation_failed |
| 오디오 | canceled, capability_unsupported, provider_rejected, provider_failed, processing_timeout, result_ingest_failed, generation_failed |
환불 규칙은 세 종류가 같습니다.
- 사용자 입력이 원인인
prompt_rejected와capability_unsupported는 환불되지 않고 과금이 유지됩니다. - 그 밖의 실패는 제공자나 시스템 원인이라 전액 환불됩니다.
- 취소(
canceled)는 전액 환불됩니다. - 영상은
billing.status(pending,charged,refunded,not_billable,quarantined)로, 오디오는billing.status(pending,charged,refunded,not_billable)로 정산 상태를 확인합니다.
접수 뒤 영상은 45분, 오디오는 10분 안에 끝나지 않으면
processing_timeout으로 닫히고 환불됩니다. 이미지도 제공자가 받은 뒤 45분을 넘기면 같은 코드로 닫힙니다.체리와 지출
- 접수하면 견적 금액이 보류됩니다. 견적과 보류 금액은 같은 계산입니다.
- 작업이 끝나면 정산되고, 실패나 취소면 환불됩니다.
- 키에 지출 한도를 걸면 기간(UTC 하루 또는 한 달) 안에 보류한 합계(환불 제외)가 한도를 넘는 요청이 거절됩니다. 거절되면 작업이 만들어지지 않습니다.
- 사용량은 설정의 개발자 사용량 화면에서 일, 키, 모델별로 봅니다.
요청 한도
시간당 호출 수는 기능마다 다르고 읽기가 쓰기의 10배입니다. 표는 API 레퍼런스의 요청 한도 절에 있습니다. 개인 키로 부른 모든 응답에는 다음 헤더가 붙습니다.
| 헤더 | 뜻 |
|---|---|
X-RateLimit-Limit | 이 버킷의 시간당 한도 |
X-RateLimit-Remaining | 남은 호출 수 |
X-RateLimit-Reset | 리셋까지 남은 초 |
Retry-After | 429에서만. 다시 보내도 되는 때까지 남은 초 |
한도 초과는 429
RATE_LIMITED이고 Retry-After 뒤에 다시 보냅니다. 키 지출 한도 초과도 429이지만 코드가 SPEND_LIMIT_EXCEEDED입니다. 두 경우를 error.code로 구분하세요. 동시 작업 한도(image_active 등)는 기다릴 초를 주지 않으니 진행 중인 작업을 기다린 뒤 다시 보냅니다.웹훅 전달 실패
알림이 가지 않는다고 작업이 실패한 것은 아닙니다. 작업은 조회로 확인합니다. 전달 상태와 다시 보내기는 웹훅을 보세요.
도움 받기
요청 id와 시각, 작업 id를 함께 알려 주세요. 키 값은 보내지 마세요.