시작하기

오류

모든 실패는 표준 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 }을, 14001은 { "required": 240, "available": 45, "topUpUrl": "https://picoberry.ai/pricing" }를 반환합니다. 제한을 하드코딩하지 말고 이 값을 읽으세요.

HTTP 상태 코드

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

오류 코드 카탈로그

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

코드	HTTP	발생 시점
1001	`401`	API 키 누락, 유효하지 않음, 또는 해지됨.
6014	`403`	계정에 활성 구독이나 완료된 크레딧 구매가 없음 — API 사용 권한 없음.
6016	`403`	키가 하루 안전 기준을 넘어 자동으로 일시 중지됨. 계정 주인이 대시보드에서 다시 켤 때까지 결과 조회·다운로드만 되므로 재시도하지 마세요.
6017	`403`	무료 계정이 유료 전용 모델(`GET /v1/models`에서 `paidOnly: true`)을 요청함. 키는 그대로 쓸 수 있으니 `paidOnly: false`인 모델로 바꾸거나 `error.details.upgradeUrl`에서 유료 플랜으로 올리세요. 모델(`model`·`engine`)을 생략하면 플랜에서 쓸 수 있는 모델이 기본으로 선택됩니다. 단, UV 언랩은 모든 엔진이 유료 전용입니다.
14001	`402`	지갑 잔액으로 작업을 처리할 수 없습니다. `error.details`에 필요한 양(`required`), 지갑에서 이 작업에 쓸 수 있는 양(`available`), 충전할 곳(`topUpUrl`)이 담겨 있습니다. 충전하기 전에는 재시도하지 말고 `GET /v1/credits`를 확인하세요.
2001	`400`	필드가 검증에 실패했습니다(타입, 범위, 또는 길이).
2012	`400`	프롬프트 또는 이미지가 콘텐츠 정책에 의해 차단되었습니다.
7002	`413`	업로드가 20 MB 제한을 초과했습니다.
7003	`400`	지원되지 않는 업로드 형식.
13001	`404`	알 수 없는 자산 id이거나, 자산이 키 소유가 아닙니다.
13005	`400`	리메시 소스는 AI로 생성된 모델이어야 합니다 — 업로드한 파일은 리메시할 수 없습니다.
13008	`400`	애니메이션 소스를 리깅할 수 없습니다 — 명확한 인간형 또는 동물형 형태가 필요합니다.
10003	`429`	IP당 또는 사용자당 요청 제한을 초과했습니다.
13002	`429`	이미 진행 중인 생성이 너무 많습니다 — 동시 실행 한도 참고. 차감 없이 거부되므로 슬롯이 나면 재시도하세요.
20001	`504`	생성 엔진이 타임아웃되었습니다. 재시도해도 안전합니다.
20002	`429`	엔진 용량이 일시적으로 가득 찼습니다. 잠시 후 재시도하세요.
20004	`400`	엔진이 입력을 거부했습니다(예: 처리할 수 없는 이미지).

처리 방법

재시도: 429, 500, 503, 504는 지수 백오프로 재시도하세요 — ~1 초에서 시작해 최대 ~30 초, 다섯 번.
재시도 금지: 400, 401, 402, 403, 404는 재시도하지 말고 요청을 고치세요(402는 먼저 충전).
429가 나면 호출 빈도를 낮추세요: 제한은 IP당 분당 240회 요청, 사용자당 분당 120회 생성 요청입니다.
200 이후에 실패한 작업(taskStatus: 3)은 자동으로 환불됩니다 — 성공한 생성에 대해서만 과금됩니다.