오류 - Zet Studio API

오류 형식

요청이 거절되면 항상 같은 모양으로 답해요.

{
  "error": {
    "code": "invalid_params",
    "message": "Check the request.",
    "request_id": "req_8f2a1c...",
    "details": [
      { "param": "aspect", "message": "Must be one of: 1:1, 16:9, 9:16, 4:3, 3:4." }
    ],
    "retryable": false,
    "retry_after_seconds": null
  }
}

필드	뜻
`code`	프로그램에서 구분할 때 쓰는 값이에요.
`message`	사람이 읽는 설명이에요. 기본은 영어이고, `Accept-Language: ko`를 보내면 한국어예요.
`request_id`	문의할 때 알려 주세요. 모든 응답의 `x-request-id` 헤더에도 있어요.
`details`	항목별 문제처럼 더 자세한 내용이에요. 없으면 `null`이에요.
`retryable`	같은 요청을 다시 보내도 되는지 알려줘요.
`retry_after_seconds`	이만큼 기다린 뒤 다시 보내요. 없으면 `null`이에요.

재시도 기준

retryable이 true일 때만 다시 보내요. retry_after_seconds가 있으면 그만큼 기다리고, 없으면 1초, 2초, 4초처럼 간격을 늘려 주세요. POST /generations는 같은 Idempotency-Key로 보내야 두 번 청구되지 않아요.

코드

상태	코드	뜻과 해결 방법
`400`	`invalid_request`	요청 형식이 잘못됐어요. `details`를 확인해 주세요.
`400`	`invalid_params`	모델에 없는 옵션이나 조합이에요. `details`에 항목별로 나와요.
`400`	`invalid_inputs`	모델이 이 입력 조합을 받지 않아요. 메시지를 확인해 주세요.
`400`	`input_not_found`	입력 파일을 찾을 수 없어요. 업로드 확인 전이거나, 지워졌거나, 다른 계정의 파일이에요.
`400`	`invalid_idempotency_key`	키 형식이 잘못됐어요.
`400`	`invalid_range`	`GET /usage`의 기간이 잘못됐어요. `from`은 `to`보다 늦을 수 없고, 기간은 366일까지예요.
`400`	`invalid_size`	파일 크기가 잘못됐어요.
`401`	`unauthorized`	키가 없거나 잘못됐어요. 인증을 봐 주세요.
`402`	`insufficient_balance`	잔액이 부족해요. 충전한 뒤 같은 키로 다시 보내면 돼요.
`403`	`api_not_enabled`	이 계정의 API 사용이 승인되지 않았어요.
`403`	`access_limited`	이 계정은 아직 쓸 수 없어요.
`404`	`not_found`	작업을 찾을 수 없어요. 다른 계정의 작업도 `404`예요.
`404`	`model_not_found`	없는 모델이에요. `GET /models`를 확인해 주세요.
`404`	`upload_not_found`	업로드를 찾을 수 없어요. 이미 지운 파일도 `404`예요.
`409`	`idempotency_conflict`	같은 키로 내용이 다른 요청을 보냈어요.
`409`	`generation_not_cancelable`	이미 시작했거나 끝난 작업이에요.
`409`	`generation_active`	진행 중인 작업은 지울 수 없어요. 끝난 뒤 다시 시도해 주세요.
`409`	`upload_incomplete`	파일이 아직 도착하지 않았어요.
`409`	`upload_in_use`	진행 중인 작업이 쓰는 파일이에요. 끝난 뒤 다시 시도해 주세요.
`413`	`payload_too_large`	요청 본문이 1MB를 넘어요.
`413`	`too_large`	파일이 20MB를 넘어요.
`415`	`unsupported_media_type`	본문은 `application/json`이어야 해요.
`415`	`unsupported_type`	PNG, JPG, WebP 이미지만 올릴 수 있어요.
`429`	`rate_limited`	호출 한도를 넘었어요. 한도를 봐 주세요.
`429`	`concurrency_limit`	동시 실행 한도를 넘었어요. 한도를 봐 주세요.
`500`	`internal`	저희 쪽 문제예요. 다시 시도해 주세요.
`501`	`storage_disabled`	파일 저장소를 쓸 수 없어요. 저희에게 알려 주세요.
`503`	`model_unavailable`	지금은 이 모델을 쓸 수 없어요. 잠시 후 다시 시도하거나 다른 모델을 골라 주세요.

작업 실패

요청은 받았지만 작업이 실패하면 HTTP 오류가 아니라 작업의 status가 failed가 되고 금액을 돌려드려요. 이유는 error.code에 있어요.

코드	뜻	할 일
`content_rejected`	콘텐츠 정책에 걸렸어요.	프롬프트나 입력 이미지를 바꿔 주세요. 그대로 다시 보내면 또 거절될 수 있어요.
`generation_failed`	그 밖의 이유로 실패했어요.	다시 시도해 주세요. 새 작업이니 새 `Idempotency-Key`를 써 주세요.

앞으로 코드가 늘어날 수 있어요. 모르는 코드는 generation_failed처럼 처리해 주세요.

MCP

MCP 도구에서만 나오는 코드예요.

상태	코드	뜻과 해결 방법
`400`	`price_over_limit`	작업 가격이 `max_spend_usd`를 넘어요. 시작하지 않았고 청구되지 않았어요.
`400`	`wrong_tool`	이 도구로 쓸 수 없는 모델이에요. 이미지 모델은 `generate_image`, 영상 모델은 `generate_video`를 써요.
`401`	`api_key_not_accepted`	이 주소는 로그인으로만 연결해요. API 키는 `https://api.studio.thezet.io/mcp`에 보내요.
`403`	`app_disconnected`	설정의 연결된 앱에서 연결을 해제했어요. 같은 화면에서 다시 허용해 주세요.
`503`	`oauth_disabled`	지금은 로그인으로 연결할 수 없어요. 잠시 후 다시 시도해 주세요.