Set spend limits and low-balance alerts

At high volume, two things matter: spend should never run past what finance approved, and production should never stop because the balance ran dry. Tovano has a control for each, under Billing.

Only owners of the organisation can change these settings. Every change is recorded under Activity.

1. Set a monthly spend limit

Open Billing → Limits and enter the limit in dollars. It applies to the whole organisation, across all projects and keys, and resets on the first day of each month (UTC).

The limit is checked before a task starts, against this month's spend plus everything already reserved. A request that would pass it is refused with:

{
  "error": {
    "type": "billing_error",
    "code": "spend_limit_reached",
    "message": "This request would pass your monthly spend limit of $60,000.00."
  }
}

Set the limit with headroom above your forecast, so a good month doesn't stop your product. Many teams set it at about 120% of the expected monthly spend and review it each quarter.

2. Set a low-balance alert

Enter an amount under Billing → Alerts. When the balance drops below it, we email the alert addresses you list there, or the billing email, or else the organisation's owners. Pick an amount that covers several days of normal use, so there is time to act.

3. Turn on auto top-up

With a card saved, auto top-up adds a fixed amount whenever the balance drops below a threshold. Volume bonus credits apply to automatic top-ups too: 2% from $1,000, 5% from $2,500 and 8% from $10,000.

For a team spending around $2,000 a day, a threshold of $10,000 and a top-up of $25,000 keeps several days of headroom and earns the 5% bonus on every top-up.

4. Handle the errors in code

Both billing errors are 402. They are not temporary, so do not retry them in a loop. Stop new work, tell the right people and show a clear message.

import { Tovano, TovanoError } from "tovano";

const tovano = new Tovano();

try {
  await tovano.tasks.create({ model: "image/demo-1", input: { prompt } });
} catch (err) {
  if (err instanceof TovanoError && err.status === 402) {
    if (err.code === "spend_limit_reached") await alertFinance("Monthly AI spend limit reached");
    if (err.code === "insufficient_credits") await alertOps("Tovano balance is empty");
    return { error: "Generation is paused. Please try again later." };
  }
  throw err;
}

5. Check the balance from your monitoring

curl https://api.tovano.ai/v1/balance -H "Authorization: Bearer $TOVANO_API_KEY"

{
  "object": "balance",
  "balance_micro": 41820000000,
  "reserved_micro": 3200000,
  "available_micro": 41816800000,
  "spent_this_month_micro": 18240110000,
  "spend_limit_micro": 60000000000,
  "currency": "usd"
}

A check every few minutes that compares spent_this_month_micro with spend_limit_micro lets you warn before the limit is reached, not after.