Units and the 402 error¶
Units are prepaid service credits. They are non-transferable, are not money, and have no monetary value outside the platform. Two kinds are metered today, separately: data units and compute units. Every rate and bundle price lives in one public catalog; this page quotes none of them.
A 402 is a refusal, not a charge
When an action would exceed your balance, the platform refuses it and returns
402, almost always before any work starts. Nothing is metered and nothing is
drawn down.
What units fund today¶
| Unit | Funds | Rate field in action_rates |
|---|---|---|
| Data | Each running collector, per UTC day | byo_collector_day_data |
| Compute | Each Hawkes fit | hawkes_fit_compute |
| Compute | Each Convection swarm, per member for every round in its round limit | swarm_round_compute |
| Compute | Each platform (managed) collector, per UTC day, on top of its data units | managed_collector_day_compute |
Platform collectors are open to selected accounts; other accounts get TIER_TOO_LOW
and can deploy a remote (bring-your-own) collector instead.
Not metered today:
- Data Governance reads draw no units.
- Clarion attestations carry no charge during the Solana devnet beta.
- Traces draw no units. Tracing is open to selected accounts (
TRACER_REQUIRES_PRO), and adding units does not open it.
How metering works¶
- Collectors. An hourly sweep charges each running collector once per UTC day, so a part day costs a full day. A deploy needs at least one data unit unless the account is on the floor, and a platform collector also needs at least one compute unit.
- Fits. The balance is checked against the fit price before the fit starts. The fit is charged only when it converges; a fit that fails, times out or does not converge draws nothing.
- Swarms. The price is
swarm_round_compute× members × the round limit, fixed when the swarm is admitted. A swarm always runs its full round limit. The balance is checked before it starts, and it is charged once, only when it converges; an aborted swarm draws nothing.
Where prices live¶
The catalog is public JSON and needs no key:
| Field | Holds |
|---|---|
tokens_per_usd |
The list rate, in units per USDC |
action_rates |
The four per-action rates in the table above |
bundles |
Each bundle's sku, kind, units, price_atomic, price_usdc and discount_pct |
signup_grant |
The units a new account receives once its email is verified |
bundles also lists networking bundles, but nothing draws networking units. The
reply also carries legacy fields such as plans and packs; nothing in them is for
sale. For a fit, fit_pricing returns the current
price so a client can report it before running. Every field, with runnable
examples: Pricing and payments.
The 402 balance errors¶
Each unit kind refuses independently. Paste either string into search to land back here:
error contains |
code |
Means |
|---|---|---|
insufficient DATA token balance ({n}) to deploy a collector |
INSUFFICIENT_DATA_TOKENS |
Not enough data units to deploy |
insufficient COMPUTE token balance ({n}) to deploy a platform agent |
INSUFFICIENT_COMPUTE_TOKENS |
Not enough compute units for a platform collector |
this fit costs {cost} compute tokens; your balance is {balance} |
none | Not enough compute units for the fit |
this run costs {cost} compute tokens; your balance is {balance} |
none | Not enough compute units for the swarm |
this fit costs {cost} compute tokens; balance fell short mid-run |
none | The balance dropped while the fit ran; it was not charged |
Collector and fit errors put payment required: before the message, so match the
substring. Collector errors carry a code and a docs_url into the
error-code index; fit and swarm errors carry no code yet.
What to do:
- New account? Verify your email; the signup grant lands then.
- Balance spent? Top-ups are not open yet; see Top-ups over x402.
- Agents: report the shortfall to the human and do not retry unchanged. See MCP errors are data, not failures.
Other 402 replies are not balance errors:
TIER_TOO_LOW,RECONCILE_REQUIRES_PRO,SSE_REQUIRES_PROandTRACER_REQUIRES_PROmark features open to selected accounts. Adding units does not clear them.CONCURRENT_CAP_REACHEDmeans the account's collector cap is in use; stop a collector to deploy another. The cap is lower on the floor.- A fit
402containingconcurrent-fit cap reachedmeans too many fits are running; wait for one to finish.
The floor¶
An account is on the floor when every unit balance is zero or below, unless it is one of the selected accounts. On the floor:
- its oldest remote collectors, up to the floor's collector cap, keep running and draw no units;
- platform collectors, and remote collectors beyond the cap, are stopped;
- new remote collectors can still be deployed up to the cap; past it, a deploy returns
CONCURRENT_CAP_REACHED; - fits and swarms return
402until compute units are added.
Reaching the floor deletes nothing: collected data, datasets and fits are kept.
Verify your email to unlock the signup grant¶
A new account receives a one-time signup grant of data and compute units, credited
once its email is verified; signup_grant in the catalog holds the amounts. Until
then the balance reads zero, so the account is on the floor and fits and platform
collectors return 402. Open the verification link; the grant lands the next time
the account's balance is read, for example when the webapp loads. Signup units may
expire or be adjusted
(Terms of Service §4).
Top-ups over x402 (coming)¶
Top-ups are not open yet. They open first on Solana devnet, for listed testers only; mainnet comes later. Check the live state, no key needed:
| Reply | Status |
|---|---|
"status": "disabled" |
OPENS SOON |
"status": "operational" with a devnet network |
OPEN · DEVNET |
"status": "degraded" |
DELAYED |
| no answer | UNAVAILABLE |
How a top-up will work:
- You buy a bundle from
bundlesin USDC on Solana, over x402 v2. Coinbase Developer Platform is the facilitator: it verifies and settles each payment and pays the Solana network fee, so the paying wallet needs USDC only. - A top-up is two HTTP calls. Prepare answers
402with the price inPAYMENT-REQUIRED; submit carries the signed payment inPAYMENT-SIGNATURE, and a settled reply returnsPAYMENT-RESPONSE. - The payment is signed on your machine. Aetelier never receives or stores wallet keys.
- Units are credited once, keyed to the payment's on-chain signature, and the receipt is fetched by memo. See I paid but my units are not credited.
- Aetelier adds the prepare step before the
402, so a stock x402 client will not work unchanged. A public, signed payer CLI is coming.
Until top-ups open, the prepare, submit and receipt calls answer 503 with code
topup_disabled, while the status endpoint answers disabled.
Once devnet opens, an account not on the tester list gets 403 with code
topup_not_allowed.
The top-up 402 asks for a payment. The balance 402s above only refuse work and
carry no x402 headers.
Bundle purchases are final except where the law requires a refund (Terms of Service §6).
Related¶
- Error-code index — every code, its verbatim string and its fix
- Feature access — features open to selected accounts, and their codes
- MCP errors are data, not failures — how a
402reads to an agent - I paid but my units are not credited — receipts by memo, and support
fit_pricing— read a fit's compute price before running it