# Limits and credits

> What a call costs, how credits are bought, and what happens at zero.

## Credits, not requests

A call costs **credits**, and different oracles can cost different numbers of
them. Today `chart`, `vector-graphics` and `coverage-policy` each cost one.

That is not a pricing gimmick. Oracles do different amounts of work to reach a
verdict, and charging per request would make the cheap ones subsidise the
expensive ones until we had to stop offering the expensive ones.

Each oracle's cost is on the [Oracles](https://docs.formalogic.io/oracles) page, and every answer
carries the `credits` it actually cost.

**A billable call is one where the check reached a verdict.** `valid` and
`invalid` both bill; `error` — our failure — is refunded and costs `0`. See
[Verdicts](https://docs.formalogic.io/verdicts).

## Credits are prepaid, and they do not expire

You hold a balance. It is the second thing a call is paid from — the first is
your plan's monthly allowance, below — and nothing resets it at the end of the
month. A new organisation starts with no balance: its calls come from the free
plan's allowance of **20 credits a month**, which is enough to find out whether
this works for you without talking to anyone.

When the balance runs low you buy more, in any amount, on the
[Credits](https://app.formalogic.io/billing) page. What you buy is added to what you have; it is not a
new allowance replacing an old one, and unused credits are never swept.

[See your plan and buy credits](https://app.formalogic.io/billing)

## Plans

An organisation carries a **plan** — `free`, `pro` or `enterprise` — and the plan
sets a **monthly allowance** of credits. Every call is paid from the allowance
first; only when the allowance is spent does a call reach your credit balance.
Credits never expire. So a `pro` organisation that uses its whole allowance in a
period pays for the rest of that period's calls from credits, and one that stays
inside it touches its credits not at all.

The allowance runs on **your billing period**. A subscriber is billed from the
day they subscribed and every month after; the allowance resets on that same
day, not on the first of the calendar month, and does not carry over. A `free`
organisation has no billing period, so its allowance resets on the first of each
calendar month.

`pro` and `enterprise` are **subscriptions**: you choose one on the
[Billing](https://app.formalogic.io/billing) page, pay by card, and it renews every month until you
cancel. Everything after that happens on the same page, with no redirect: switch
between the paid plans, cancel, take a cancellation back, change the card the
plan renews on, and read your invoices. An upgrade takes effect at once: the
difference for the rest of the period is charged now (any credit on your
account is used first), and the allowance rises with it. A downgrade waits for
the end of the period you have paid for — you keep the larger allowance until
then, the renewal is billed at the lower price, and nothing is charged or
credited when you make the switch; you can take it back until the period ends.
Cancelling is always at the end of the period you have paid for: the plan keeps
working until then, then drops to `free`, and until then you can keep it after
all. Cancelling drops a downgrade you had scheduled.

If you need volume beyond `enterprise`, an invoice rather than a card, or a
support commitment, ask us.

Every oracle is included regardless of plan. What you buy is volume, never
access — an agent whose tool set changes with an invoice is an agent that stops
reaching for tools.

## Running out

A call that cannot be paid for answers `402 QUOTA_EXCEEDED`, with the numbers in
`context`:

```json
{
  "error": "QUOTA_EXCEEDED",
  "detail": "this organisation does not have enough credits for that call",
  "context": {
    "balance": "0",
    "needed": "1",
    "limit": "20",
    "used": "20",
    "plan": "free"
  }
}
```

`balance` is what you hold and `needed` is what the call would have cost — those
two are what to act on. `limit` and `used` describe the current allowance period
— the calendar month on `free`, your billing period on a subscription. They are
for display; `balance` and `needed` decide whether a call proceeds.

Every value in `context` is a string. That is true of every error this API
returns, not a quirk of this one.

Credits are per **organisation**, not per key. Minting a second key does not buy
a second balance — see [Authentication](https://docs.formalogic.io/authentication) for what a second
key is actually for.

## Requests per minute

Each plan publishes a `requests_per_minute` figure, and you can read it in the
console.

Pace your calls to it; it may be enforced without notice. What decides whether
a call proceeds is your allowance and credit balance.

## Keys

`max_live_keys` bounds how many unrevoked keys an organisation may hold at once.
It is not a security control — credits are shared across all of them — it keeps
the key list readable and bounds runaway automation. Revoking frees a slot
immediately.

## Watching spend

The [Usage](https://app.formalogic.io/usage) page shows what this period has spent and a log of every
metered call: which oracle, which key, what verdict, what it cost. Refunded calls
appear with `0` credits rather than not appearing, so an outage is visible after
the fact.

The [Credits](https://app.formalogic.io/billing) page shows the balance itself and every movement of it —
each purchase, any opening credit, and what has been spent since.