시작하기

오류

모든 실패는 표준 HTTP 상태 코드와 동일한 JSON 봉투를 사용합니다 — 다른 무엇을 읽기 전에 먼저 success로 분기하세요.

두 가지 실패 유형 요청 오류(잘못된 키, 잘못된 파라미터, 할당량 초과)는 아래 봉투를 담은 non-2xx 응답으로 동기적으로 반환됩니다. 생성 실패는 나중에 발생합니다: 생성 요청은 200을 반환하지만 이후 자산이 taskStatus: 3으로 끝나며 — 해당 크레딧은 자동으로 환불됩니다. 이유를 확인하려면 자산의 errorCategory / errorDetail을 읽으세요. 비동기 & 폴링을 참고하세요.

오류 봉투

오류 응답
{
  "success": false,
  "error": {
    "code": 14001,
    "message": "Insufficient credit",
    "httpStatus": 402,
    "timestamp": "2026-08-05T09:12:00.000Z",
    "path": "/v1/models/from-text"
  }
}

오류 응답에는 data가 없습니다. error.code는 안정적인 숫자 식별자입니다 — 사람이 읽는 용도라 바뀔 수 있는 error.message가 아니라 이 값으로 분기하세요.

일부 코드의 error.details 일부 오류는 실패의 실시간 수치를 담은 error.details 객체를 함께 반환합니다 — 예: 13002는 { "total": 15, "maxTotal": 15 }을 반환합니다. 제한을 하드코딩하지 말고 이 값을 읽으세요.

HTTP 상태 코드

상태의미
400검증 — 잘못되거나 누락된 파라미터, 지원되지 않는 엔진/형식, 또는 읽을 수 없는 이미지.
401API 키 누락, 유효하지 않음, 또는 해지됨.
402작업을 처리하기에 크레딧이 부족합니다.
403계정에 API 사용 권한이 없음 — 활성 구독이나 완료된 크레딧 구매가 없습니다.
404자산 또는 컬렉션을 찾을 수 없거나, 키 소유가 아닙니다.
413업로드한 파일이 20 MB를 초과했습니다.
429요청 제한(10003), 동시 생성 초과(13002), 또는 업스트림 엔진의 할당량을 초과했습니다. 백오프 후 재시도하세요.
500 · 503 · 504서버 오류, 점검, 또는 업스트림 엔진 타임아웃. 백오프하며 재시도하세요.

오류 코드 카탈로그

/v1에서 가장 자주 마주치는 코드입니다. 숫자 code는 릴리스 간에 안정적으로 유지됩니다.

코드HTTP발생 시점
1001401API 키 누락, 유효하지 않음, 또는 해지됨.
6014403계정에 활성 구독이나 완료된 크레딧 구매가 없음 — API 사용 권한 없음.
14001402지갑 잔액으로 작업을 처리할 수 없습니다. 충전하거나 GET /v1/credits를 확인하세요.
2001400필드가 검증에 실패했습니다(타입, 범위, 또는 길이).
2012400프롬프트 또는 이미지가 콘텐츠 정책에 의해 차단되었습니다.
7002413업로드가 20 MB 제한을 초과했습니다.
7003400지원되지 않는 업로드 형식.
13001404알 수 없는 자산 id이거나, 자산이 키 소유가 아닙니다.
13005400리메시 소스는 AI로 생성된 모델이어야 합니다 — 업로드한 파일은 리메시할 수 없습니다.
13008400애니메이션 소스를 리깅할 수 없습니다 — 명확한 인간형 또는 동물형 형태가 필요합니다.
10003429IP당 또는 사용자당 요청 제한을 초과했습니다.
13002429이미 진행 중인 생성이 너무 많습니다 — 동시 실행 한도 참고. 차감 없이 거부되므로 슬롯이 나면 재시도하세요.
20001504생성 엔진이 타임아웃되었습니다. 재시도해도 안전합니다.
20002429엔진 용량이 일시적으로 가득 찼습니다. 잠시 후 재시도하세요.
20004400엔진이 입력을 거부했습니다(예: 처리할 수 없는 이미지).

처리 방법