Credits and retries | border.bot API docs

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

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. 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. 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.