Reference

Errors and troubleshooting

API error codes, purchase reconciliation results, CLI exit codes and fixes for the failures people hit.

View as Markdown

Every API error has a stable code and a message that names the problem. Every CLI failure maps to an exit code you can script against.

API error shape

json
{
  "error": "no_entitlement",
  "message": "No active license for <slug>@<version>. Claim or buy a license on the patch page first."
}

API error codes

Status Code Meaning
400 invalid_request The JSON body is missing or failed validation. The message names each bad field.
400 invalid_query A query parameter on GET /api/v1/patches has the wrong type or value.
400 wallet_link_failed The wallet challenge expired or was already used, was issued for another chain, the signature doesn't match the address, or the wallet is linked to another account.
401 unauthenticated No session, or no registry key with the scope this route needs. Revoked keys also get this.
403 no_entitlement You don't hold an active license for that version. Claim or buy one on the patch page.
404 not_found The patch, version or comparison doesn't exist, isn't public, or isn't published.
410 download_expired The download link was already used or is older than five minutes. Request a new install ticket.
422 digest_mismatch An install event reported an adapter digest that doesn't match the version.

Browser sign-in routes don't return JSON errors. They redirect to /sign-in?error=invalid_email or /sign-in?error=link_invalid.

Purchase reconciliation results

POST /api/v1/chain/reconcile-purchase answers 200 with a status rather than an error, because most outcomes are temporary.

Status or reason Meaning
not_found No transaction with that hash on this chain.
pending The transaction exists but isn't mined yet. Try again shortly.
failed The transaction reverted. No license was bought.
wrong_contract The transaction didn't touch this environment's license market, or no market is configured here.
no_license_event It called the market but emitted no purchase event.
confirming Mined, waiting for the required number of confirmations.
confirmed Recorded. Each purchase in the response says whether it created an entitlement.
version_not_registered_here The purchased version isn't registered in this environment.
terms_digest_mismatch The purchase was made under different terms than the current listing.
buyer_wallet_not_linked The buyer address isn't linked to a Retoque account. Link it, then reconcile again.

CLI exit codes

Code Meaning
0 Success.
1 General error: network failure, bad input, invalid slug or version, patch not installed, expired download link, a failed doctor check, or interrupted.
2 Refused: a signature, digest, package layout or compatibility check failed, and nothing was installed or changed. Also argument usage errors.
3 Not logged in, key rejected, or no license for the version.

Troubleshooting

cannot reach registry at http://localhost:3400

The CLI uses the local development URL by default. Set RETOQUE_API_URL, add apiBaseUrl to ~/.config/retoque/config.json, or pass --api-url. See Configuration.

refusing http URL ...: only https (or http on localhost) is allowed

The CLI won't send your key over plain HTTP to a remote host. Use the registry's https URL.

registry keys start with 'rtq_'

You pasted something else, often a model provider key. Create a registry key in your workspace under API keys.

registry key rejected (exit 3)

The key was revoked, mistyped, or lacks the scope the command needs. login needs registry:read, install needs artifacts:download, and install reports need installs:report. Create a new key with the scopes you need and run retoque login again.

no license for this patch version (exit 3)

Claim the free license or complete a purchase for that exact version on the patch page. A license for another version doesn't count.

compatibility preflight INCOMPATIBLE or UNKNOWN_UNTESTED (exit 2)

--model must be the repository and full 40-character commit in the manifest. A branch name such as main is UNKNOWN_UNTESTED because it can move. Run retoque patches inspect <slug>@<version> to see the exact reference. --experimental-override exists for experiments only and is recorded in the lockfile.

Download links are single-use and last five minutes. Run install again to get a new ticket.

signature rejected: publisher key ... is not trusted (exit 2)

The package was signed by a key that isn't the pinned first-party key or in your trustedKeys. Only add a key you have confirmed out of band.

package sha256 mismatch or sha256 ... vs manifest (exit 2)

The bytes differ from what was signed or listed. Don't use the package. Delete any partial download and try again. If it repeats, the package or the registry record is wrong.

tokenizer.json sha256 mismatch (exit 2)

Your cached base snapshot doesn't match the tokenizer the patch was evaluated with. Download the exact revision again into your Hugging Face cache.

already exists with different contents; published versions are immutable

Something else occupies ~/.retoque/patches/<slug>/<version>. Inspect it before deleting it, then install again.

`retoque run` needs the runtime extra

Install it with pip install 'retoque[runtime]'.

run is slow or the process is killed

Qwen2.5-1.5B in float32 needs about 7 GB of free memory. On a laptop CPU, expect seconds to minutes per answer. Use a machine with more memory or a GPU host you control.

<slug>@<version> is not installed; installed versions: ...

rollback only switches between installed versions. Install the target version first.