> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# bead credit troubleshooting

> Follow bead credit troubleshooting steps to resolve holds, funding refusals, pending purchases, and automatic refill failures.

Start bead credit troubleshooting by checking the returned error and your available balance. A positive balance can still have funds reserved for authorized work.

## Insufficient credit

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead balance
bead limits
```

HTTP 402 `insufficient_credit` means funds or the applicable key budget cannot cover the commitment. Reduce size or duration, release finished work, or [add credit](https://docs.bead.run/platform/top-up.md). Trial credit may also have expired.

A temporary machine stops at its funded deadline. Adding credit alone does not extend the timeout; request an extension before it ends. A persistent machine can pause when rolling funding cannot renew. Read its grace deadline before resuming.

## Balance is positive but available credit is low

Reservations cover authorized exposure before measured usage settles. A stopped or deleted machine can retain a hold for uncertain authorized usage while reconciliation completes. Deletion does not guess that missing usage was zero.

A key's consumed-plus-reserved ceiling can also prevent work while the organization still has funds. See [API key budgets](https://docs.bead.run/platform/key-budgets.md).

## A purchase is pending

Repeat `bead topup` with the same amount and private purchase file. Keep the original delivery key. Follow the returned retry interval.

Only verified settlement adds funds. A Checkout success redirect is not settlement evidence. Starting a second purchase can create another payment; recover the original purchase first.

## Automatic refill failed

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead billing autorefill show
bead billing autorefill recover
```

Complete the returned hosted payment flow if recovery is still available. Otherwise make a normal top-up. Save or replace the card if needed, then explicitly enable automatic refill again.

A monthly cap pause needs explicit resumption after the cap increases or the month changes. Refills do not bypass funded deadlines. See [Automatic credit refill](https://docs.bead.run/platform/auto-refill.md).

## A refund or dispute changed the balance

Successful refunds and lost disputes reverse purchased credit. If funds were already spent, the balance can become negative. New funds settle that debt before funding new work; existing authorized usage can still settle.

Keep purchase identifiers and sanitized error codes for investigation. Keep keys, purchase secrets, and private delivery material out of shared logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.