Skip to content

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: disabled reads OPENS SOON, operational on a devnet network reads OPEN · DEVNET, degraded reads DELAYED, and a failed fetch reads UNAVAILABLE. A mainnet network still 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:

{ "tool": "fit_hawkes", "arguments": { "dataset_id": "ds_9f3a…", "tolerance": 500 } }

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.