Hedra 402 INSUFFICIENT_BALANCE vs Sume insufficient_credits

On Hedra, a freshly created key cannot submit anything until the wallet has funds: POST /models/{id} returns 402 INSUFFICIENT_BALANCE. Sume answers an under-funded request with 402 insufficient_credits. Treat both as a billing state, not a bug, and do not retry the same request in a loop.

The Hedra facts are from its API Quickstart Guide and developer platform post; the Sume facts are from Errors and rate limits and MCP tools and gates. Read 2026-10-02.

What does Hedra do when the wallet is empty?

The quickstart says that until you add funds, POST /models/{id} returns 402 INSUFFICIENT_BALANCE, and it lists a /balance endpoint to check the wallet. The developer post says Hedra moved from expiring credits to usage-based dollars, so you pay for what you generate and top up when you need to.

It also lists preflight cost estimates, and the quickstart lists POST /v3/models/{id}/estimate, so you can price a job before you submit it.

What does Sume do?

The error table lists 402 insufficient_credits: the balance is not sufficient for the requested generation. The body is the standard envelope with code, message and a request_id that is safe to share with support. A separate 429 queue_full means workspace concurrency plus queue capacity is full, which is a different problem and should be retried later.

To preflight, the MCP tools offer dry_run=true, described as an admission and cost preview that does not submit the job, and generation_admission_preview. The docs recommend one of them before expensive bursts.

Handling the two errors

The right reaction is the same on both sides: stop, tell a person to top up, then resubmit once.

What should my code do on a 402?

Surface the error to an operator instead of looping. After the balance is fixed, resubmit with the same Idempotency-Key you used before, so that if the first request had partly gone through Sume does not create a second paid job. Keep the request_id from the failed response in your log. For a batch, run a dry run on one representative request first and multiply the estimate by the batch size before you submit the rest.