# Errors and troubleshooting

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

Source: https://retoque.xyz/docs/errors
Markdown: https://retoque.xyz/docs/md/errors

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](https://retoque.xyz/docs/cli#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 link expired or already used`

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.