API 문서 · 안정성

오류 코드

통일된 오류 본문과 전체 오류 코드.

모든 오류는 동일한 구조를 사용합니다(오른쪽 예제 참고). 아래 표는 API가 반환할 수 있는 error.code와 HTTP 상태 코드입니다. 하나의 상태 코드에 여러 오류 코드가 대응할 수 있습니다.

HTTP	code	상황	재시도	권장 조치
400	`invalid_request`	JSON 형식 오류, Content-Type이 application/json이 아님, 또는 Idempotency-Key 누락 / 길이 초과. 요청 본문이 1 MB를 넘으면 413	불가	요청을 수정해 다시 전송
401	`invalid_api_key`	Key가 없거나 폐기, 만료, 비활성화됨	불가	콘솔에서 Key 상태 확인
401	`unauthenticated`	콘솔 세션에 로그인하지 않았거나 세션이 만료됨	불가	다시 로그인
402	`quota_exceeded`	계정의 사용 가능 한도 부족, 예치 상한이 max_budget 초과(param은 max_budget), 또는 에셋 저장 공간 가득 참	불가	한도를 충전하거나 max_budget을 조정하거나 에셋을 정리한 뒤 재시도
402	`key_limit_exceeded`	Key의 누적 또는 일일 한도 부족	불가	Key 한도를 조정한 뒤 재시도
403	`permission_denied`	Key에 scope가 없거나, 모델이 Key 허용 목록에 없거나, 계정에 해당 모델 권한이 없음	불가	콘솔에서 Key 권한을 추가하거나 운영팀에 모델 활성화 요청
403	`csrf_failed`	콘솔 요청에 CSRF 토큰이 없거나 만료됨	불가	페이지를 새로고침한 뒤 재시도
403	`account_suspended`	계정이 정지됨	불가	운영팀에 문의
404	`not_found`	리소스가 없거나 본인 소유가 아님	불가	ID가 올바른지 확인
404	`not_available`	글로벌 사이트에서만 제공하는 기능으로 이 사이트에서는 사용할 수 없음	불가	해당 기능을 제공하는 사이트 이용
403	`terms_required`	최신 충전 약관에 동의하지 않음	불가	충전 약관을 읽고 동의한 뒤 재시도
409	`idempotency_conflict`	멱등 키는 같지만 요청 본문이 다름	불가	새 요청에는 새 멱등 키 사용
409	`conflict`	리소스 상태 충돌	불가	최신 상태를 다시 조회한 뒤 진행
409	`group_not_empty`	그룹에 아직 에셋이 있음	불가	그룹 내 에셋을 먼저 옮기거나 삭제
422	`invalid_parameter`	파라미터가 잘못되었거나 지원하지 않는 조합(임의로 버리지 않음)	불가	기능표를 참고해 파라미터 수정
422	`asset_not_ready`	에셋이 아직 처리 중	가능	상태가 available이 된 뒤 재시도
422	`authorization_required`	실존 인물 에셋에 유효한 승인이 없음	불가	실존 인물 승인 완료 후 재시도
429	`rate_limited`	Key의 RPM 초과, 또는 계정 / Key의 동시 실행 한도 초과	가능	Retry-After에 따라 백오프 후 재시도
500	`internal_error`	플랫폼 내부 오류	가능	같은 멱등 키로 재시도

retryable이 true이면 백오프 후 재시도할 수 있습니다. 작업 생성을 재시도할 때는 반드시 같은 Idempotency-Key를 사용하세요.

접수 이후에 발생한 실패(예: 일시적으로 사용 가능한 경로가 없음)는 API 오류로 반환되지 않고 작업의 error.code에 나타납니다. 작업 실패 코드를 참고하세요.

오류 응답

HTTP/1.1 422 Unprocessable Entity
X-Request-Id: req_xxx

{
  "error": {
    "code": "asset_not_ready",
    "message": "에셋 asset_xxx가 아직 처리 중입니다. 상태가 available로 바뀐 뒤 다시 시도하세요",
    "param": "inputs[0].asset_id",
    "retryable": true,
    "request_id": "req_xxx"
  }
}