Errors and fixes

How to read an error

The local API, the command line with --json, and the SDK all describe an error the same way:

{ "ok": false, "network": "mainnet-beta",
  "error": { "code": "needs_sol",
             "message": "the agent wallet holds 0.0050 SOL; a deposit needs about 0.02 SOL for buffer rent (refunded) and fees.",
             "retryable": false,
             "details": { "haveSol": "0.0050", "needSol": "0.02" } },
  "requestId": "req_..." }

ok

false for an error, true for success.

error.code

A short, fixed name. Programs should check this, never the message.

error.message

A sentence for people: what happened and, usually, what to do.

error.retryable

true: nothing was sent and the same request may be tried again later, with the same idempotency key. false: something must change first. Then send it with a new idempotency key: the old key keeps returning this same error.

error.details

Extra facts when there are some, like needSol, the relayer's reason, or the idempotency key.

requestId

The ID of this call in the local server's log. The command line does not print one.

The API also sets the HTTP status (401, 409, 503…) and, for waits, a Retry-After header in seconds.

# a wrong token on purpose: -i shows the HTTP status too
curl -s -i -H "Authorization: Bearer wrong" http://127.0.0.1:8081/v1/balance

# Invoke-RestMethod throws on an error; the body is in ErrorDetails
try {
  Invoke-RestMethod -Headers @{ Authorization = "Bearer wrong" } http://127.0.0.1:8081/v1/balance
} catch {
  $e = ($_.ErrorDetails.Message | ConvertFrom-Json).error
  "$($e.code) (retryable: $($e.retryable)): $($e.message)"
}

import pathlib, requests

API = "http://127.0.0.1:8081/v1"
token = (pathlib.Path.home() / ".h081" / "api-token").read_text().strip()

r = requests.get(API + "/balance", headers={"Authorization": "Bearer " + token})
data = r.json()
if data["ok"]:
    print(data["result"]["shielded"])
else:
    err = data["error"]
    print(r.status_code, err["code"], err["retryable"], err["message"])
    print(err.get("details"))

import { H081, classify } from '@h081lll/agent';

const bank = await H081.open();
console.log((await bank.deposit('5')).result);   // the plan: nothing is sent
try {
  await bank.deposit('5', { confirm: true, idempotencyKey: 'dep-1' });
} catch (e) {
  const err = classify(e);               // { code, status, retryable, message, details }
  console.log(err.code, err.status, err.retryable, err.message, err.details);
}

HTTP/1.1 401 Unauthorized
content-type: application/json; charset=utf-8
...
{"ok":false,"network":"mainnet-beta","error":{"code":"unauthorized","message":"missing or wrong token: send Authorization: Bearer <the token in ~/.h081/api-token>","retryable":false},"requestId":"req_..."}

With Claude, a refused action comes back as a tool result with the same code and message, so Claude can explain it and change course.

Every error code

Grouped by what kind of problem it is. "Retry?" says whether the same request may simply be sent again later. On phones, the tables scroll sideways.

Your request

Something about the call itself: the token, the address, the format.

Retries and idempotency keys

The safety net that stops a payment from going out twice.

Money, fees and limits

Nothing was sent. Something needs topping up, or the amount is over a limit.

Network, relayer and timing

Usually brief. Most are safe to retry with the same key.

On-chain refusals

A Solana program said no. The message explains which rule.

Setup

Something on this computer is missing.

Common situations

Not enough SOL (needs_sol)

SOL is Solana's own coin. Every action pays a small network fee in SOL, and some stage a proof on chain first, which needs a refundable deposit. The error tells you what the wallet has (details.haveSol) and roughly what it needs (details.needSol).

1. Find the agent's address

   npx -y @h081lll/agent address

2. Send SOL to it

   From any Solana wallet or exchange. Send a little more than needSol.

3. Check it arrived, then see the plan again

   npx -y @h081lll/agent balance --fresh

   npx -y @h081lll/agent deposit 5

   From the API or the SDK, send it with a new idempotency key. The key you used before keeps returning needs_sol. (The command line makes a new key on every run.)

Relayer busy or unavailable

The relayer sends withdrawals for you. When it is busy (relayer_busy) or answers "too many requests" (rate_limited), H081 already waited and tried once more before giving you the error. Nothing was sent.

{ "ok": false, "network": "mainnet-beta",
  "error": { "code": "relayer_busy", "message": "...", "retryable": true,
             "details": { "relayerStatus": 503, "reason": "busy" } },
  "requestId": "req_..." }

1. Wait a few seconds

   Use Retry-After when the response has it.

2. Send the same request with the same idempotency key

   The key was released because nothing was sent, so it runs again. If it had gone through, you would get the stored answer instead: it can never pay twice.

   npx -y @h081lll/agent withdraw 2 --to <a wallet that never touched the agent>

   npx -y @h081lll/agent withdraw 2 --to <a wallet that never touched the agent> --yes --idempotency-key wd-7

3. Still down after a while?

   If the relayer stays unreachable (relayer_unavailable), wait and try later. --direct skips the relayer, but then your agent wallet is public as the sender.

A retry loop that is safe to copy: it retries only when retryable is true, keeps the same key, and stops at outcome_unknown.

import pathlib, time, uuid, requests

API = "http://127.0.0.1:8081/v1"
s = requests.Session()
s.headers["Authorization"] = "Bearer " + (pathlib.Path.home() / ".h081" / "api-token").read_text().strip()

def send(path, body, key, tries=3):
    """A confirmed send that retries only when the API says it is safe."""
    for attempt in range(tries):
        r = s.post(API + path, json={**body, "confirm": True}, headers={"Idempotency-Key": key})
        data = r.json()
        if data["ok"]:
            return data["result"]
        err = data["error"]
        if err["code"] == "outcome_unknown":
            raise RuntimeError("It may have been sent. Check GET /v1/balance?fresh=1 before anything else.")
        if not err["retryable"] or attempt == tries - 1:
            raise RuntimeError(err["code"] + ": " + err["message"])
        time.sleep(int(r.headers.get("Retry-After", "5")))   # same key: it can never send twice

body = {"usdg": "2", "to": "<fresh wallet>"}
print(s.post(API + "/withdraw", json=body).json()["result"])  # the plan: no "confirm", nothing is sent

key = str(uuid.uuid4())                                       # one key per payment
print(send("/withdraw", body, key))

import { H081, classify } from '@h081lll/agent';

const bank = await H081.open();
const to = '<fresh wallet>';
console.log((await bank.withdraw('2', { to })).result);       // the plan: nothing is sent
const key = crypto.randomUUID();                              // one key per payment

for (let attempt = 1; ; attempt++) {
  try {
    console.log(await bank.withdraw('2', { to, confirm: true, idempotencyKey: key }));
    break;
  } catch (e) {
    const err = classify(e);
    if (err.code === 'outcome_unknown') { console.log('Maybe sent. Check first:', await bank.balance({ fresh: true })); break; }
    if (!err.retryable || attempt === 3) throw e;
    await new Promise((r) => setTimeout(r, 5000));           // same key: it can never send twice
  }
}

Outcome unknown (outcome_unknown)

It happens when the local server stopped in the middle of a send, or the connection to the relayer or Solana broke while sending. It is never marked retryable, and the same key keeps giving this answer, so a script cannot pay twice by accident.

1. Check the balance and recent history

   npx -y @h081lll/agent balance --fresh
   npx -y @h081lll/agent history --limit 5

   From the API: GET /v1/balance?fresh=1 and GET /v1/history.

2. Decide

   Balance dropped, or the money arrived: it went through. Do nothing. Balance unchanged and nothing arrived: send it again with a new idempotency key.

Stale root (stale_root)

A proof is made against a snapshot of the bank (its "Merkle root" and a timestamp). If other people used the bank while your proof was being made, the snapshot is out of date and the program refuses it. Nothing was sent.

{ "ok": false, "network": "mainnet-beta",
  "error": { "code": "stale_root", "message": "...", "retryable": true, "details": { ... } },
  "requestId": "req_..." }

Fix: send the same request again; the same idempotency key is fine. A new proof is made against the current snapshot. in_flight is similar: another operation from your account is spending the same money right now, so let it finish first.

Proof files missing or damaged

Proofs need proving files (about 98 MB in total), downloaded once into ~/.h081/circuits and checked against pinned fingerprints. serve downloads them in the background; the first proof also fetches what it needs.

circuits_missing: download them.

npx -y @h081lll/agent fetch-circuits

circuit_hash_mismatch: a file is damaged or not from H081, and it is refused. Delete the folder and download again. If it happens again, tell us at @H081CAP.

rm -rf ~/.h081/circuits
npx -y @h081lll/agent fetch-circuits

Remove-Item -Recurse -Force $HOME\.h081\circuits
npx -y @h081lll/agent fetch-circuits

Cannot reach Solana (rpc_unreachable) or "429 Too Many Requests"

The RPC is the Solana server your computer talks to. The public one limits how often you can ask. Use your own RPC URL (a free tier is enough):

npx -y @h081lll/agent init --rpc <your Solana RPC URL>

Or set H081_RPC_URL for one program. Only the RPC's host name is ever shown in messages and logs.

Command line exit codes

Every command ends with a number that scripts can check:

With --json, stdout (the command's normal output) carries only the JSON envelope; messages and logs go to stderr (its separate error output), so you can pipe stdout into another program.

npx -y @h081lll/agent deposit 5 --yes --json

{
  "ok": false,
  "network": "mainnet-beta",
  "error": {
    "code": "needs_sol",
    "message": "the agent wallet holds 0.0050 SOL; a deposit needs about 0.02 SOL for buffer rent (refunded) and fees.",
    "retryable": false,
    "details": { "haveSol": "0.0050", "needSol": "0.02" }
  }
}

npx -y @h081lll/agent balance --json > balance.json
echo "exit code: $?"

npx -y @h081lll/agent balance --json > balance.json
"exit code: $LASTEXITCODE"

• RelatedPrivacy and safetyWhat is public, your key, ceilings and safe retries.→
• ReferenceLocal APIEvery route, with examples.→

New here? The 5-minute quickstart does a first private payment end to end. The package is @h081lll/agent on npm. Questions: @H081CAP on X.