Skip to content

Error-code index

Platform API error bodies carry three fields:

{
  "error": "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 human-readable string, code is stable and machine-matchable, and docs_url lands on this page at the section for that code. Agents should branch on code whenever a body carries one, not on the prose. Fit and swarm errors carry error only, with no code yet; match their message instead. Top-up endpoints answer with their own lowercase codes, such as topup_disabled, and no docs_url; they are listed in I paid but my units are not credited. For the narrative recovery patterns, read MCP errors are data, not failures.

Most errors here are the platform enforcing a balance, access or input rule: the action was refused, not charged. A 402 here refuses work; it is not a payment request and carries no x402 headers.

Nothing to buy

Some messages still say tokens, tier, plan or upgrade. Nothing can be bought to open a feature. Gated features are open to selected accounts, and units do not open them. Top-ups are not open yet: the public status reads disabled, shown as OPENS SOON — see Top-ups over x402.

INSUFFICIENT_DATA_TOKENS

HTTP 402. Verbatim: insufficient DATA token balance ({n}) to deploy a collector.

A collector deploy needs at least one data unit, and the balance is below that. Nothing was charged and nothing was deleted. An account with no units of any kind is on the floor instead and does not get this code: it can still deploy remote collectors up to the floor's cap. Fix: report the shortfall; top-ups are not open yet — see Units and the 402 error.

INSUFFICIENT_COMPUTE_TOKENS

HTTP 402. Verbatim: insufficient COMPUTE token balance ({n}) to deploy a platform agent.

Only a platform (managed) collector deploy sends this code: it needs at least one compute unit on top of its data unit. Platform collectors are open to selected accounts, so other accounts get TIER_TOO_LOW first. A fit or swarm that is short of compute units answers 402 with no code, such as this fit costs {cost} compute tokens; your balance is {balance}. Same semantics: refused, not charged. Fix: deploy a remote collector, which draws data units only, or report the shortfall — see Units and the 402 error.

EMAIL_UNVERIFIED

HTTP 402, reserved. Not sent today: no current 402 message names email verification, so no response carries this code.

An account whose email is not verified holds no units, so it is on the floor and gets the floor's answers instead: a platform collector returns TIER_TOO_LOW, a fit returns this fit costs {cost} compute tokens; your balance is 0 with no code, and a collector past the floor's cap returns CONCURRENT_CAP_REACHED. In the webapp, collector deploys and fits stay off until you verify. Fix: open the verification link we emailed you, then load the webapp; the signup grant lands then.

TIER_TOO_LOW

HTTP 402. Verbatim: managed agents are not included in the {tier} tier — upgrade to Base or higher, or deploy a BYO (remote) agent.

Platform (managed) collectors are open to selected accounts, and this account is not one of them. Units do not clear it, and nothing can be bought to clear it. Remote (BYO) collectors are open to every account. Fix: deploy a remote collector — see Feature access.

RECONCILE_REQUIRES_PRO

HTTP 402. Verbatim: live reconciliation requires the Pro tier or higher — current tier: {tier}.

Live reconciliation is open to selected accounts. Fix: deploy without [collect.reconcile] enabled = true — see Feature access.

SSE_REQUIRES_PRO

HTTP 402. Verbatim: live collector-state streaming is included from the Pro plan.

The live collector-state stream (GET /api/collectors/state/stream) is open to selected accounts. Fix: poll collector_status or collector_health, which work on every account — see Feature access.

TRACER_REQUIRES_PRO

HTTP 402. Verbatim: trace configuration is included from the Pro plan.

Tracing is open to selected accounts. The gate covers every /api/tracer/ route, reads included, and units do not open it. Fix: none yet; report the code — see Feature access.

CONCURRENT_CAP_REACHED

HTTP 402. Verbatim: concurrent-collector cap reached ({in_flight}/{cap}) for the {tier} tier — release a collector or upgrade.

The account's concurrent-collector cap is fully in use. The cap is lower on the floor, where the message reads for the free tier floor. Fix: stop a collector you no longer need with stop_collector, then retry — see Platform limits.

PAYMENT_REQUIRED

HTTP 402. Fallback code for a 402 message that matches none of the codes above; no current message maps to it.

Read the error string, report it, and do not retry unchanged. Fit and swarm 402s carry no code; match their message in Units and the 402 error and Feature access.

API_KEY_INVALID

HTTP 401. Verbatim: unauthorized.

The request carried no credential, or one that is malformed, expired or revoked. Fix: create a new API key in the webapp (Settings → Security) and retry with it. Keys are revocable; a key that worked yesterday may have been rotated.

FORBIDDEN

HTTP 403. Verbatim prefix: forbidden:.

The credential is valid but does not own the resource it addressed. Fix: check that the service_id / resource id belongs to this account. A platform collector on Solana for an account not on the preset's allowlist is also refused here; deploy a remote collector instead — see Feature access.

NOT_FOUND

HTTP 404. Verbatim prefix: not found:.

The id in the request does not exist on this account. Ids are account-scoped; copy them from a list call rather than constructing them.

CONFLICT

HTTP 409. Verbatim prefix: conflict:.

The request collides with current state (for example, a duplicate deploy of the same resource). Re-read current state with a list call, then retry with the conflict resolved.

VALIDATION_ERROR

HTTP 400. Verbatim prefix: validation error:.

The request failed admission checks before touching any state. The message names the offending field — one collector runs one symbol, and Platform limits lists the enforced boundaries. A governance read past the account's window_secs ceiling also lands here; retry inside the ceiling the message names.

RATE_LIMITED

HTTP 429. Verbatim prefix: too many requests:.

Back off and retry with exponential delay. Agents: treat this as pacing feedback, not failure.

SERVICE_UNAVAILABLE

HTTP 503. The message is passed through and names the actionable condition.

A backing service is temporarily unreachable or an operator condition (such as a missing agent image) blocks the action. On tracing and the live stream, entitlement check unavailable means the access check could not run. Check the status page and platform_health; if both are green, retry with backoff.

INTERNAL

HTTP 500. Verbatim: internal error. Also HTTP 503 with service unavailable when a backing queue is unreachable.

A platform-side fault; detail stays server-side. Retry once with backoff; if it repeats, check the status page and email [email protected] with the time (and timezone) and what you called — see Getting help.