Start · What can go wrong
What can go wrong, and what to do
Each section says what happens and what you do. The codes in backticks are the ones the SDK, the
CLI (with --json) and the MCP server return. When a result carries retryAfterSeconds, wait at
least that long before you try again.
Three rules cover most cases:
- Never pay a second time for the same purchase. Resume the existing purchase with
statusandopen. A saved live or accepted purchase blocks another buy withpurchase_open. Only an explicit--force(MCPforce: true) creates another purchase despite that saved purchase. - Keep your purchase ID and your backup secret. They let you check, resume and open a purchase. Losing them does not lose the file: the same wallet can recover it.
- Exit code 4 means wait. The CLI exits with it, and CLI JSON and MCP errors carry it as
exitCode, for anything still pending or uncertain. It is not proof that the payment failed.
Exit codes: 1 other failure, 2 invalid input or configuration, 3 human approval or contract trust needed, 4 pending or uncertain.
Setup
These errors report invalid input or missing configuration. All exit with code 2.
credentials_required: no wallet is selected, or its key is missing. A person signs in withannon login --wallet near(or--wallet evm) and approves each payment in the browser. For an agent, the owner runsannon init --agentonce with a key reference, a recovery identity that matches the key and a daily budget, as in agents.md.signer_required:annon init --agentgot no key reference or more than one, or a remote signer without exactly one credential reference. The owner runs it again with exactly one of--evm-key-file,--near-key-file,--solana-key-file,--key-env,--keychain-entry,--new-keyor--signer(annon --helplists them). In a browser shop it means no wallet is connected: connect one and try again.invalid_arguments: a command, option or value is not valid. Check the command withannon --helpor CLI.md; for MCP, check the tool's input schema.
Before you pay
The quote or the purchase expired
- 1Click: after review and recovery proof, at least ten minutes must remain before the deposit
cutoff, or the command returns
quote_expired. Do not fund that quote. After confirming that no deposit was sent, request a fresh quote withbuy --forceusing the same URL and source options (MCPforce: true). Keep the old purchase record. - Base: the SDK signs a payment authorization lasting at most 180 seconds. Keep the saved
purchase and check
status. Start another purchase only after final chain evidence establishes that the authorization expired or was cancelled without payment. A payment that settled before its deadline can still be unlocked later. - NEAR: a purchase is valid for one hour after it is prepared. The SDK pays right away, so this only matters if you pay by hand. A payment that arrives after expiry is not accepted and is refunded in full to your NEAR Intents account (below).
Do not use a local deadline or an uncertain response as evidence that payment failed. Check the saved purchase before starting another one.
The file has no Base route
route_unavailable (exit code 2, "This file does not support the selected payment route."): the
file's final on-chain terms have no Base payee, so it cannot be paid directly on Base. Files from NEAR
and Solana sellers are like this. You get this before any wallet or payment step, and the host
refuses such a payment too. Use near, or 1click with Base as the source chain
(annon buy URL --route 1click --from-chain base, or an MCP origin the owner configured for Base).
An EVM wallet without --route gets origin_required for such a file, with the same advice.
1Click refuses the quote
1Click can refuse a quote because of its route minimum or available liquidity. When supplied,
minimumAmountUsdc gives the reported minimum. Do not send a deposit without a valid quote. Use
another available payment route if the file's price cannot be quoted. The demo file costs 0.10 USDC,
below the 1Click minimum from Base when we checked, so from Base buy it with near or base.
A refused quote still leaves a saved purchase, so until it expires (within an hour) the next buy of
the same file stops with purchase_open, although no payment was sent. When there was no deposit
address, no deposit can have been sent: buy with another route and --force (MCP: force: true).
The relayer refuses or is busy
not_sponsored: the relayer does not sponsor the Base unlock for this file. You get this before your wallet signs the payment. Pay on NEAR or through 1Click instead.relayer_unavailableorrelayer_rate_limited: the relayer is busy or paused. Wait forretryAfterSecondsand try again.budgetwhile selling: the relayer has paused new listings, or a daily sponsorship limit is used up. Buying keeps working. Wait forretryAfterSeconds, or list with your own NEAR account.
If you have already paid, a busy relayer delays the unlock but never cancels your purchase. See the payment is still pending.
You have no NEAR for gas
You need NEAR only on the NEAR route. Other routes:
- Base: only USDC on Base. You sign an authorization; you need no ETH and no NEAR.
- 1Click: a supported source asset and enough funds for the quoted deposit and source-chain transaction costs.
NEAR accounts also pay a little storage to sell or recover. See NEAR accounts.
The wallet is on the wrong network
wrong_chain ("Select Base in the wallet."): the SDK asks the wallet to switch to Base. If the wallet
cannot, switch it yourself and try again. The payment was not signed.
smart_wallet_unsupported: the Base route needs an ordinary wallet account (an EOA), not a smart
contract wallet. Use another account or another route. insufficient_balance means there is not
enough USDC on Base: send at least the price in USDC on Base to the paying address (for an agent, the
identity annon init --agent printed). The Base route needs no ETH. The refused attempt may still
count against the daily budget until its window ends.
The file is moderated or taken down
A seller can name a moderator who can stop new key releases for that file. Before buying a moderated
file you must accept that moderator explicitly (unknown_moderator; pass --moderator account.near
on buy once you trust it). If the file is already taken down, buy stops with taken_down before
you pay, and the file host answers 410.
While you pay
The payment is still pending
settlement_pending (exit code 4) means the payment or the key release is not final yet. Keep the
saved purchase.
- Base: a Base payment must reach Safe finality before NEAR can verify it. Poll
statusand honorretryAfterSeconds. - 1Click: a swap can take several minutes, and its
SUCCESSstatus alone does not prove Annon accepted the purchase. - Relayer busy: the unlock is queued and retried. It is delayed, not cancelled.
What you do: wait for retryAfterSeconds (30 seconds when nothing more precise is known), then run
annon status 0xPURCHASE_ID again. The MCP server refuses to retry before that time.
transaction_uncertain (also exit code 4) means a transaction may have been sent and its result is
not confirmed: a reply was lost, or a browser wallet did not report back after its send was called.
It includes txHash and purchaseId when they are known; a hash is never invented. annon buy
can also return state: "uncertain" with exit code 4, and annon status then reports
submission: "uncertain" until the purchase is accepted. Keep that evidence and check the existing
purchase or transaction. Do not pay again to resolve uncertainty.
You closed the tab or the program crashed
The purchase is saved, encrypted, before payment authorization or submission. A separate wallet signature may be requested first to prove recovery ownership.
- Browser: return to the same page in the same browser and resume the saved purchase.
lease_busymeans another tab holds it. An active tab can renew its hold; after it stops renewing, the hold expires within two minutes. Clearing site data deletes the local record. Export receipts for a separate copy, or recover accepted purchases with the same wallet. - CLI or MCP: run
annon status 0xPURCHASE_ID. The ID appears inbuyoutput and encrypted backups understateDir/backups. If you lost it, runannon recover --recovery kind:idwith the same configured wallet, replacingkind:idwith its identity. Recovery reports successful grants and per-purchase errors. Remove leftover.tmpfiles and.annon-spool-*directories beside the output before opening again.
While you sell
The shop refuses the upload
A shop sets its own hosting and sponsorship limits (shops and limits).
rate_limited means the host's daily upload count for your wallet, your IP address or the whole
shop is used up: wait retryAfterSeconds. limited means a relayer admission limit is reached,
such as an hourly request limit or a daily sponsorship quota: wait retryAfterSeconds, then resume
the saved sale. Do not start a new listing to bypass the limit. host_capacity means the host has no room or does not
accept uploads from you; try later or host the file yourself. too_large means the file is above
the shop's size limit. A refusal before you sign anything costs nothing. A shop that publishes
rules shows them in annon shops and in the annon share result.
The sale stopped part way
Resume the saved sale with the same file (annon share FILE --resume 0xFILE_ID --shop SHOP_ID,
or annon sell FILE --resume 0xFILE_ID for a self-hosted sale); never start a new one for the same
file. Resume checks
the chain before it repeats any step, so an uncertain transaction is never sent twice blindly. Keep
the backup secret: without it the saved sale cannot be resumed.
An unfinished verified upload is kept for 24 hours from body verification. After that, requests
return upload_expired. The host permits restaging unfinished uploads, but this does not guarantee
that every saved CLI checkpoint can resume automatically. Keep the original file and saved seller
state; if resumption cannot finish, serve the same registered ciphertext from another host. A file
that was published and later expired cannot be republished on that host under the same file ID.
not_sponsored when you register with an EVM or Solana wallet means the relayer does not sponsor
this registration. defdone's relayer sponsors files its shop hosts (hosted selling) and the sellers
it lists. Use hosted selling, run your own relayer, or sell from a NEAR account.
If the amount was wrong
The SDK always pays the exact price, on every route. These cases come from manual transfers or other software.
You paid less than the price
An underpayment never opens the file.
- NEAR or 1Click: a valid payment below the price is refunded in full to your NEAR Intents account. The purchase is not used up, so you can pay it correctly or start a new one. See refunds for how to withdraw.
- Base: your wallet signs for exactly the price, and the file host refuses any other amount before it settles anything.
You paid more than the price
- NEAR: the purchase is accepted and the excess is refunded to your NEAR Intents account.
- 1Click: the quote requests delivery of the exact file price. Source-deposit refunds follow 1Click's quote and refund rules, including any refund fee. Check the saved swap status before sending more funds or starting another purchase.
- Base: your wallet signs for exactly the price.
On Base, always pay through an Annon client. A plain USDC transfer to a file's Base address is not a purchase: it opens nothing, it goes to the seller's recipients, and Annon cannot send it back. Contact the seller.
The 1Click deposit was too small or too late
Send exactly the amount in the instructions, include the memo if there is one, and make sure the
deposit is confirmed before depositBefore. Do not deposit after it, even if the address still
accepts transfers.
A small deposit can remain INCOMPLETE_DEPOSIT; do not assume it has been refunded. A late deposit
may be refunded by 1Click, may still produce an accepted Annon purchase, or may reach Annon after
purchase expiry. With a valid Annon refund identity, a delivery refused after expiry is refunded in
full to that NEAR Intents account. Check both the saved swap status and Annon purchase status before
taking another payment action. Source-chain refunds follow the quote's refund rules and may incur a
fee.
Refunds in your NEAR Intents account
Refunds from the contract go to the NEAR Intents account of the wallet you bought with: your EVM address, your Solana key, or your NEAR account.
With a valid Annon refund identity, the contract records the refund for that identity's NEAR Intents balance. Crediting the balance is asynchronous; a transfer to Annon is not proof that the refund has already arrived.
Withdraw using a NEAR Intents interface that supports the same identity and its USDC balance. Annon's CLI and MCP server do not provide a refund-withdrawal command. If you cannot locate or withdraw the balance, contact hello@annon.dev with your purchase ID and transaction hash. Never send a private key, seed phrase or backup secret.
After you bought
Download limit reached
download_limited (HTTP 429): on the demo host, each purchase can download its file three times
right away. After that you wait:
| Download | Available |
|---|---|
| 1st to 3rd | Right away |
| 4th | 15 minutes after the 3rd finished |
| 5th | 2 hours after the 4th finished |
| Each later one | 24 hours after the previous one finished |
retryAfterSeconds says how long to wait before requesting another download. Save the file once
and keep it.
The host counts a download when it finishes transmitting the complete encrypted body. A later decryption or local-save failure does not undo that count. Interrupted transmissions do not count. Recovery on another device does not reset the count, and the initial automatic save uses one download.
The download was interrupted
A running SDK download can resume from its first unchecked chunk. The host allows an interrupted
logical attempt to resume within ten minutes of its last transmitted byte and within thirty minutes
of the attempt's start. Restarting the program does not preserve the client's checked-chunk offset:
run open again with the saved purchase.
download_in_progress means another download of the same purchase is running; the SDK waits a few
seconds and retries. Existing output files are not overwritten (output_exists); choose another
output name.
Opening on a new device
Use the same wallet you bought with. You never pay again.
- EVM or Solana: recovery costs you nothing.
- NEAR account: prepay a little contract storage first. See NEAR accounts.
Configure the reviewed deployment, NEAR wallet and backup secret first. Replace account, purchase ID and file URL placeholders with your own values.
annon recover --wallet near --recovery near:YOUR_ACCOUNT.near
annon open 0xPURCHASE_ID --url https://demo.annon.dev/f/FILE --output file.pdf
The file was deleted from the demo host
Demo-host uploads expire seven days after first publication, except the configured canonical demo
file. After expiry, new offers and downloads are refused with file_expired (HTTP 410); an already
active download may finish. Keep your own copy. The demo itself runs until 18 November 2026, at the
latest 19 November.
Your accepted purchase remains on chain. If another host serves the same checked encrypted file, use
annon open 0xPURCHASE_ID --url https://OTHER_HOST/FILE --output file.pdf. For a local encrypted
copy, use annon open file.pay2 --purchase /path/purchase-backup.json --output file.pdf.
The file was taken down after you bought it
A moderator's takedown blocks new key requests, including recovery. A request already sent to MPC can still complete. Keep any copy you have already opened. A valid NEAR or 1Click payment received after takedown is not accepted as a purchase and is refunded in full to its designated NEAR Intents account.
Report a problem
- A security vulnerability: report it privately through the Security tab of the GitHub repository, then Report a vulnerability. Please do not open a public issue.
- A file on the demo host, a missing refund, or anything else: write to hello@annon.dev.
Include the purchase ID, file ID, transaction hash and error code when you have them. Never send your backup secret, a private key or a seed phrase. We will never ask for them.