MCP errors are data, not failures¶
For agents. A backend failure from the aetelier-mcp server returns as an ordinary
result, not a protocol error. Read it and adapt in the same loop. Nothing below is a
dead end; each maps to a concrete next action.
{
"ok": false,
"error": "<service> 402: payment required: insufficient DATA token balance (0) to deploy a collector",
"code": "INSUFFICIENT_DATA_TOKENS",
"docs_url": "https://aetelier.xyz/docs/help/errors/#insufficient_data_tokens"
}
error is the backend message behind a <service> <status>: prefix. code and
docs_url appear when the backend sends them, and docs_url lands on the
error-code index, the per-code catalog. Branch on code when it is
present and on the message when it is not. This page is the narrative recovery guide.
Health first
Call platform_health before real work. If a
service reads anything other than ok, that capability is unreachable — retry
later rather than hammering it.
Field guide¶
| Status / signal | Means | Do this |
|---|---|---|
401 |
API key missing, wrong, revoked or expired | Re-mint the key in the webapp (Settings → Security); set it as AETELIER_API_KEY for the local binary, or send it as Authorization: Bearer <key> to the hosted endpoint. Do not retry unchanged |
402 |
Refused, not charged: units short, not open for this account, or a cap reached | Sort it with Reading a 402. Do not retry until the cause changes |
403 |
Authenticated, but not your resource | Do not retry. Confirm the id belongs to the caller; re-list to get a current one |
429 |
Rate limited | Back off and retry with increasing delay. Do not tighten the loop |
400 with Not converged after |
The fit did not converge at the given tolerance, and nothing was charged | Raise tolerance above the server default of 50 and refit; raise it again if it still fails |
| not-found for an id | The collector, fit, or dataset id is wrong or gone | Re-list (list_collectors, list_fits, list_datasets) to get a current id |
Reading a 402¶
A 402 from these tools is a refusal, not a payment request. It carries no x402
headers, and the refused action was not charged. Sort it into one of three groups
below.
Fit 402s carry no code yet, so match them on the message; a code on them is
coming. Every 402 message starts with payment required:, so match the rest as a
substring.
Units short¶
code |
Message contains | Means |
|---|---|---|
INSUFFICIENT_DATA_TOKENS |
insufficient DATA token balance |
Collector deploy refused: data units below one |
INSUFFICIENT_COMPUTE_TOKENS |
insufficient COMPUTE token balance |
Platform collector deploy refused: compute units below one |
| none yet | this fit costs {cost} compute tokens; your balance is {balance} |
Fit refused before it ran |
| none yet | this fit costs {cost} compute tokens; balance fell short mid-run |
Fit ran, but was not charged and returns no fit |
INSUFFICIENT_COMPUTE_TOKENS comes only from a platform collector deploy over the
REST API. deploy_collector registers remote collectors only, so it never sends it.
Do this: stop, and report the shortfall to the human — the action, its cost, and
the balance. Read a cost before acting with
fit_pricing or the public catalog at
https://aetelier.xyz/api/payments/catalog (no key): action_rates holds the
per-action rates and tokens_per_usd the list rate in units per US dollar.
- An account whose email is not verified holds no units. Verifying the email credits the signup grant the next time the account opens the webapp.
- An account with no units at all still deploys remote collectors, up to a lower cap.
- Top-ups are not open yet. They open first on Solana devnet for listed testers, in
USDC over x402, and mainnet comes later. Read the state at
https://aetelier.xyz/payments/topup/status:disabledreads OPENS SOON,operationalon a devnetnetworkreads OPEN · DEVNET,degradedreads DELAYED, and a failed fetch reads UNAVAILABLE. A mainnetnetworkstill reads OPENS SOON. - The MCP server has no balance or top-up tool yet; both are coming, and so is a public, signed CLI payer.
Not open for this account¶
These features are open to selected accounts. Adding units does not change that, and
nothing can be bought to open them. {tier} is a slug the server fills in.
The current tools do not trigger these codes: deploy_collector registers remote
collectors only and asks for no live reconciliation, and no tool opens the live
collector stream or tracing. An agent calling the REST API directly can meet them.
code |
Message contains | Do this |
|---|---|---|
TIER_TOO_LOW |
managed agents are not included in the {tier} tier |
Deploy a remote collector instead; deploy_collector always registers one |
RECONCILE_REQUIRES_PRO |
live reconciliation requires the Pro tier or higher |
Redeploy without [collect.reconcile] enabled = true |
SSE_REQUIRES_PRO |
live collector-state streaming is included from the Pro plan |
Poll collector_status or collector_health instead |
TRACER_REQUIRES_PRO |
trace configuration is included from the Pro plan |
Report it and move on; reading traces is gated too |
Cap reached¶
code |
Message contains | Do this |
|---|---|---|
CONCURRENT_CAP_REACHED |
concurrent-collector cap reached |
Stop a collector you no longer need with stop_collector, and retry once it has released. The cap is lower at a zero balance |
| none yet | concurrent-fit cap reached |
Wait for a running fit to finish, then retry |
| none yet | the zero-balance floor allows |
The daily fit allowance at a zero balance is used. Retry after 00:00 UTC |
PAYMENT_REQUIRED is the fallback for any other coded
402. Read error, report it, and do not retry unchanged.
A worked recovery¶
A fit that does not reach the convergence threshold returns a 400:
{ "ok": false, "error": "<service> 400: validation error: estimation did not produce a usable result: Not converged after {iterations} iterations (gradient norm = {norm})" }
The agent reads it and retries with a looser tolerance than the default 50 — the
error is the instruction:
A 402 on a fit is not a convergence problem: no tolerance changes it. Stop the
loop and report it as above. A longer recovery is in
Worked examples → Flow 2.
No "contact support" is emitted machine-side¶
The server never returns a contact support string, a phone number, or a ticket id in
a tool result. Every machine-side error is actionable by the caller — re-mint,
report a shortfall, deploy a remote collector, stop a collector, wait, back off,
loosen, or re-list. Escalation to a human is a last resort for a human operator, documented in
Getting help; it is never part of the agent loop.
Related¶
- Error-code index — every code, its verbatim string, and the fix
- Tool reference — the result contract per tool
- Worked examples — full ask → tool-sequence → recovery flows
- Aetelier for agents — capability map, gating, identifiers
- Units and the 402 error · Feature access — what
402gates resolve to