Avatar video 402 insufficient_credits: what Sume reserves first

A 402 insufficient_credits on an avatar video means Sume could not reserve the estimated cost from your workspace balance at submit time. The error comes before provider work starts, so nothing was rendered and nothing was captured.

The fix is to lower the estimate or raise the balance, then retry the same request with the same Idempotency-Key.

What does Sume reserve, and when?

Paid generation uses public Sume USD estimates. When a request is accepted, Sume reserves the estimated amount. A job that completes captures the reserved usage. A job that fails, and a submit that fails queue admission, releases or refunds the reservation where applicable.

So the 402 is an admission check, not a bill. You are charged only on successful completion.

Why is my estimate bigger than I expected?

Avatar video cost follows the estimated duration of the script or scene plan and the chosen quality tier. Because the video must estimate to 4-60 seconds, a long script reserves more than a short one. The tier changes the render path: standard is the fastest, plus is the default when you omit quality, and max is the highest quality with slower turnaround.

Multi-scene plans add up: silence scenes and spoken scenes both count toward the planned duration.

How do I check the balance and the cost first?

Read the balance with GET /v1/balance and the ledger with GET /v1/usage; the docs call those the billing records. On the hosted MCP server, paid tools accept dry_run=true for an admission and cost preview that does not submit a job, and an optional max_spend_usd that is enforced only when you pass it.

For a plain API call, use the preview route to approve composition before you pay for the full render.

curl https://api.sume.com/v1/balance \
  -H "Authorization: Bearer $SUME_API_KEY"
curl -X POST https://api.sume.com/v1/avatar-1.0/talking-video \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: avatar-launch-001" \
  -d '{"avatar_handle":"sume_clawra","script":"Short and sweet.","quality":"standard"}'

What should my client do on a 402?

Stop retrying: more attempts will hit the same check. The docs say to upgrade the plan or wait for included Gen$, or to submit a cheaper request, and not to assume prepaid top-ups exist. A retry after you fix the balance should reuse the same Idempotency-Key if the body is unchanged. If you changed the body, for example by dropping quality to standard, use a new key, because the same key with a different payload returns 409 idempotency_conflict.

Do not confuse it with 429 queue_full, which is capacity, or 429 rate_limited, which is request volume. Those errors say to wait; the 402 says to change the money or the request.

How do I avoid paying twice for a retry?

Always send an Idempotency-Key on a paid submit that may be retried. A timeout on your side is not a failed job: the job may already exist, and resubmitting without a key creates a second paid job. See retry an avatar video request without double billing for the full pattern, and Errors and rate limits for the complete code table.