Sume API 크레딧 부족 오류 402: 충전 후 재시도하기

Sume API가 돌려준 402 insufficient_credits는 워크스페이스 잔액으로 요청의 예상 비용을 감당할 수 없어서, Sume가 작업을 시작하기 전에 요청을 거부했고 아무것도 청구하지 않았다는 뜻입니다. GET /v1/balance로 잔액을 확인하고, 대시보드의 Billing & subscription 페이지에서 충전한 뒤 요청을 다시 보내세요.

아래 단계는 2026-09-26에 확인한 Sume 문서 Generation admission, 오류와 비용 (영문), 결제와 크레딧, Usage 페이지에서 가져왔습니다. 공통 오류 봉투는 Sume API 오류와 요청 한도에서 다룹니다.

402 insufficient_credits는 무슨 뜻인가요?

Sume는 제출 시 유료 요청의 예상 USD 비용을 예약(선차감)합니다. 워크스페이스 잔액에서 그 금액을 예약할 수 없으면 프로바이더 작업이 시작되기 전에 제출이 402 insufficient_credits로 실패하며, 생성 Job은 시작되지 않습니다. Format 실행에서는 같은 지갑 게이트가 실행을 만드는 시점에 있습니다. 워크스페이스가 실행 비용을 감당할 수 있어야 하며, 그렇지 않으면 아무것도 실행되지 않습니다.

Format 실행을 만드는 요청에서는 오류에 next_action: add_funds와 retryable: false도 담깁니다. 충전하지 않고 다시 보내면 같은 응답이 돌아옵니다.

잔액은 어떻게 확인하나요?

같은 키로 GET /v1/balance를 호출하세요. 읽기 전용이고 키의 워크스페이스로 범위가 제한되며, 잔액은 USD 기준입니다. data.balance에는 available_amount_usd_micros, available_amount_usd_cents, 반올림한 센트 값인 레거시 available_credits, 그리고 state가 담깁니다. state는 funded이거나, 워크스페이스에 쓸 수 있는 USD 잔액이 없거나 아직 잔액 행이 없으면 empty입니다. 잔액 행이 없으면 오류가 아니라 명시적인 영으로 읽힙니다. 필드 세부 사항은 API 레퍼런스에 있습니다.

GET /v1/usage는 잔액의 바탕이 되는 원장 행을 나열하며, 여기에는 예약, 확정, 환불, 충전, 그랜트가 포함될 수 있습니다. 402를 받은 뒤에만 확인하지 말고, 대량 제출 전에도 잔액을 확인하세요.

curl https://api.sume.com/v1/balance \
  -H "Authorization: Bearer $SUME_API_KEY"

어떻게 충전하나요?

충전은 API가 아니라 대시보드에서 합니다. 예전 문서에서 Credits라고 부르던 Billing & subscription 페이지를 열면 요금제 상태와 사용 가능한 잔액을 확인하고, Developer API 사용을 위한 크레딧을 살 수 있습니다. 워크스페이스에 결제가 설정돼 있으면 대시보드에서 수동 충전을 시작할 수 있고, 결제가 완료되면 사용량 원장에 충전 내역과 갱신된 잔액이 나타날 수 있습니다.

공개 Developer API는 현재 잔액과 사용량 조회만 제공하고 충전 엔드포인트는 없으므로, 402를 루프로 재시도하지 말고 결제 담당자에게 넘기세요. 지갑과 구매 금액은 Sume 요금 체계에서 다룹니다.

402를 받은 뒤에는 어떻게 재시도하나요?

먼저 잔액 문제를 해결한 뒤 요청을 다시 보내거나, 대신 요청 비용을 낮추세요. 402로 실패한 Format 실행이나 대량 실행 생성 요청은 Idempotency-Key를 해제했으므로, 같은 키로 재시도하세요.

TypeScript SDK에서 402는 SumeInsufficientCreditsError에 대응하며, 각 SumeApiError 하위 클래스에는 nextAction이 있습니다. 실행 헬퍼는 항상 SumeRunRequestError 자체를 던지므로, 그 status나 code로 분기하세요.

import { SumeRunRequestError } from "@sume-com/sdk";

try {
  const run = await subscribeFormatRun({ client, path, body });
} catch (error) {
  if (
    error instanceof SumeRunRequestError &&
    (error.status === 402 || error.code === "insufficient_credits")
  ) {
    return alertBillingAdmin(error.requestId); // next_action: "add_funds"
  }
  throw error;
}

충전하면 429도 해결되나요?

아닙니다. 처리 동시성 한도는 요금제로만 정해지며 선불 충전으로는 올라가지 않으므로, 429에는 돈이 아니라 기다림이나 백오프가 필요합니다. queue_full과 rate_limited는 Sume 영상 Job 동시성과 큐에서 설명합니다.