Insufficient credits error 402 on the Sume API: add funds and retry

A 402 insufficient_credits from the Sume API means the workspace balance cannot cover the estimated cost of the request, so Sume refused it before any work started and charged nothing. Check the balance with GET /v1/balance, add funds on the dashboard's Billing & subscription page, and send the request again.

The steps below come from Sume's Generation admission, Errors and spend, Billing and credits, and Usage docs pages, read on 2026-09-26. The shared error envelope is covered in Sume API errors and rate limits.

What does 402 insufficient_credits mean?

Sume reserves a paid request's estimated USD cost at submit. When it cannot reserve that amount from the workspace balance, the submit fails with 402 insufficient_credits before provider work starts, and no generation job is started. On a Format run the same wallet gate sits at create: the workspace must be able to fund the run, or nothing runs.

On a Format run create, the error also carries next_action: add_funds and retryable: false. Resending without topping up returns the same answer.

How do I check the balance?

Call GET /v1/balance with the same key. It is read-only and scoped to the key's workspace, and the balance is USD-denominated. data.balance carries available_amount_usd_micros, available_amount_usd_cents, a legacy rounded-cents available_credits, and state: funded, or empty when the workspace has no spendable USD balance or no balance row yet. A missing balance row reads as an explicit zero, not an error. Field details are in the API reference.

GET /v1/usage lists the ledger rows behind it, which can include reservations, captures, refunds, top-ups, and grants. Check the balance before a bulk submit, not only after a 402.

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

How do I add funds?

Top-ups happen in the dashboard, not the API. Open Billing & subscription, the page older docs called Credits, to see plan status and available balance and to buy credits for Developer API usage. The dashboard can start a manual top-up when billing is configured for the workspace; after checkout completes, the usage ledger can show the top-up and the updated balance.

The public Developer API currently exposes balance and usage reads, not a top-up endpoint, so route a 402 to whoever manages billing rather than retrying it in a loop. How Sume pricing works covers the wallet and purchase amounts.

How do I retry after a 402?

Fix the balance first, then send the request again, or lower the request's cost instead. A Format run or bulk-run create that failed with 402 released its Idempotency-Key, so retry it with the same key.

In the TypeScript SDK, a 402 maps to SumeInsufficientCreditsError, and each SumeApiError subclass carries nextAction. The run helpers always throw SumeRunRequestError itself, so branch on its status or 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;
}

Will adding funds fix a 429 too?

No. Prepaid top-ups do not raise the processing concurrency limit, which is plan-only, so a 429 needs waiting or backoff rather than money. Video job concurrency and queueing explains queue_full and rate_limited.