Skip to content

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:

curl -s https://aetelier.xyz/api/payments/catalog | jq '.action_rates'
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:

insufficient DATA token balance
insufficient COMPUTE token balance
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:

  1. New account? Verify your email; the signup grant lands then.
  2. Balance spent? Top-ups are not open yet; see Top-ups over x402.
  3. 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_PRO and TRACER_REQUIRES_PRO mark features open to selected accounts. Adding units does not clear them.
  • CONCURRENT_CAP_REACHED means the account's collector cap is in use; stop a collector to deploy another. The cap is lower on the floor.
  • A fit 402 containing concurrent-fit cap reached means 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 402 until 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:

curl -s https://aetelier.xyz/payments/topup/status
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 bundles in 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 402 with the price in PAYMENT-REQUIRED; submit carries the signed payment in PAYMENT-SIGNATURE, and a settled reply returns PAYMENT-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).