오류 처리

API는 일반적인 HTTP 상태 코드를 사용합니다. 2xx은 성공, 4xx은 요청을 수정해야 함, 5xx는 당사 또는 상위 서비스에서 오류가 발생했음을 뜻합니다. 모든 오류 응답은 같은 JSON 구조이므로 한곳에서 처리할 수 있습니다.

오류 형식#

{
  "error": {
    "code": "invalid_request",
    "message": "\"resolution\" must be one of: 480p, 720p",
    "param": "resolution"
  }
}

• code — 안정적이고 기계가 읽을 수 있는 문자열입니다. 메시지가 아니라 이 값을 기준으로 분기하세요.
• message — 로그에 안전하게 남길 수 있는 사용자용 설명입니다. 문구는 바뀔 수 있습니다.
• param — 특정 요청 필드가 오류 원인일 때 포함됩니다.

오류 코드#

생성 과정에서 발생하는 오류#

HTTP 오류는 요청 자체가 거부되어 요금이 청구되지 않았다는 뜻입니다. 접수 후 실패하는 생성 작업은 다릅니다. 작업이 바로 실패하더라도 API 호출(POST /run)은 HTTP 202 응답으로 성공합니다. 생성 객체에는 status 필드 값(failed)과 error 객체가 포함됩니다. 보류 금액은 자동 환불됩니다. 같은 객체는 GET /generations, 웹훅 페이로드, MCP 도구 결과에서도 확인할 수 있습니다.

{
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "ByteDance's safety review for Seedance 2.0 Fast rejected this request (the prompt or an input file).",
    "reason": "content_blocked",
    "hint": "Describe the character's look instead of naming a copyrighted character or real person, keep it non-explicit, or try another model.",
    "retryable": false,
    "refunded": true,
    "detail": "요청이 콘텐츠 안전성 검토를 통과하지 못했습니다. 프롬프트를 수정한 뒤 다시 시도하세요."
  }
}

code는 출시 이후 문서화된 네 가지 상위 분류 값 중 하나입니다. 정확한 실패 이유는 reason에서 확인할 수 있습니다. 이를 기준으로 분기하고 사용자에게 message 및 hint 값을 표시하세요. retryable 필드는 같은 요청을 다시 보내도 되는지를 나타냅니다. 필드 변경 정보(param)와 제공자 원문(detail)도 확인하세요.

요청으로 인해 발생한 실패(content_blocked, invalid_input에 대한 파일 거부, input_unreachable)는 다른 제공자에서 재시도하지 않습니다. 다시 요청해도 거부되기 때문입니다. 장애와 제공자 오류는 같은 가격으로 이용할 수 있는 모든 경로에서 우선 재시도합니다. 자세한 내용: 실패 및 환불.

모델 서비스에서 입력 파일을 다운로드하지 못했다고 하면 보통 저희가 직접 다운로드를 시도합니다. 가능하면 저희가 호스팅하는 사본으로 작업을 다시 시도합니다. 가격은 그대로이며, 사용자가 변경할 것은 없습니다. 생성 내역에는 전송한 URL이 계속 표시되고, 사본은 각 생성 작업의 보관 기간에 따라 함께 삭제됩니다. 따라서 input_unreachable은 파일을 전혀 다운로드하지 못했다는 뜻일 가능성이 큽니다. 로그인이 필요하거나, 서명된 링크가 만료되었거나, 파일로 직접 연결되지 않거나, 호스트가 요청을 거부한 경우일 수 있습니다. 이미지 최대 30MB, 동영상 200MB, 오디오 50MB까지 복사하며, 더 크거나 읽을 수 없는 파일은 invalid_input 오류로 처리됩니다.

안전하게 재시도하기#

지수 백오프와 지터를 적용해 429, 500, 502, 503을 재시도하세요. 그 외 4xx 오류는 수정 없이 재시도하지 마세요. 같은 방식으로 다시 실패합니다.

const RETRYABLE = new Set([429, 500, 502, 503]);

export async function postWithRetry(url, headers, body, attempts = 5) {
  let resp;
  for (let attempt = 0; attempt < attempts; attempt++) {
    resp = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
    if (!RETRYABLE.has(resp.status)) break;
    // exponential backoff with jitter: ~1s, 2s, 4s, 8s…
    await new Promise((r) => setTimeout(r, Math.min(2 ** attempt, 30) * 1000 + Math.random() * 1000));
  }
  const data = await resp.json();
  if (!resp.ok) throw new Error(`${resp.status} ${data.error.code}: ${data.error.message}`);
  return data;
}

import random, time, requests

RETRYABLE = {429, 500, 502, 503}

def post_with_retry(url, headers, json, attempts=5):
    for attempt in range(attempts):
        resp = requests.post(url, headers=headers, json=json, timeout=30)
        if resp.status_code not in RETRYABLE:
            break
        # exponential backoff with jitter: ~1s, 2s, 4s, 8s…
        time.sleep(min(2 ** attempt, 30) + random.random())
    if not resp.ok:
        err = resp.json()["error"]
        raise RuntimeError(f"{resp.status_code} {err['code']}: {err['message']}")
    return resp.json()

유효성 검사 예시#

유효성 검사 메시지에는 필드명과 허용 값이 표시되므로 개발자에게 그대로 보여줄 수 있습니다:

[
  {
    "error": {
      "code": "invalid_request",
      "message": "\"prompt\" is required",
      "param": "prompt"
    }
  },
  {
    "error": {
      "code": "invalid_request",
      "message": "Unknown parameter \"resoluton\"",
      "param": "resoluton"
    }
  },
  {
    "error": {
      "code": "not_found",
      "message": "Unknown endpoint \"bytedance/seedance-2.0-fast/text-to-gif\". See GET /api/v1/models."
    }
  }
]

실행하지 않고도 요청 가격을 확인할 수 있습니다. POST /api/v1/quote/{endpoint}이 가격에 영향을 주는 필드를 검증하고 비용을 반환합니다. API 레퍼런스를 참고하세요.