# Credits and retries

> How border.bot charges prepaid credits per API call, refunds failed calls, and makes retries safe with Idempotency-Key.

Source: https://border.bot/docs/credits
Last updated: 2026-10-09

> Documentation index: https://border.bot/llms.txt. Every page is Markdown at its URL + `.md`.


## Credits

Billable calls spend prepaid credits from the workspace. Each action has a fixed price, set on the server; `GET /v1/pricing` (no key needed) lists them, and so does the [pricing page](https://border.bot/pricing). New workspaces get free credits to start with.

The price is taken before the work runs, in one atomic step, so the balance can't go below zero. If the call then fails, the credits are refunded automatically. Every billable response carries:

| Header                | Meaning                           |
| --------------------- | --------------------------------- |
| `X-Credits-Charged`   | Credits this call cost.           |
| `X-Credits-Remaining` | The workspace balance afterwards. |

A workspace without enough credits gets `402 insufficient_credits`, with `details.required` and `details.balance`. Top up in the [dashboard](https://app.border.bot). `GET /v1/credits` returns the balance and ledger, and `GET /v1/usage` the usage history.

## Safe retries

Send an `Idempotency-Key` header (any unique string, such as a UUID) on billable `POST` requests. Repeating a request with the same key returns the original result and doesn't charge again. While the first request is still running, a repeat gets `409 conflict`; wait and retry.

```bash
curl -X POST https://api.border.bot/v1/classify \
  -H "Authorization: Bearer $BORDERBOT_API_KEY" \
  -H "Idempotency-Key: 4f9c1a52-0b8e-4c5e-9d0a-5d1f2b8a7e31" \
  -H "Content-Type: application/json" \
  -d '{"description":"Stainless steel water bottle, 750 ml","destinationCountry":"GB"}'
```

Retry on `429`, `502`, `504` and network errors, with the same idempotency key and backoff (honour `Retry-After`). Don't retry other `4xx` errors unchanged: fix the request first.