open-standards/wai/wai-quantum/docs/job-refusals.md

# Job refusals: codes

The reader gives every refusal and warning about a program's text a code
(`Q…`, [qasm-diagnostics.md](qasm-diagnostics.md)). What is asked of a
program has codes of its own (`J…`): the request, the method, an intent, a
repair, the host that runs the job, a program the job service writes for a
task (`J080` to `J082`), and a qudit job (`J090` to `J092`). A refusal reads,
on every surface:

```text
stabilizer needs a Clifford circuit: … [J011]
```

A refusal whose cause is a reader's code keeps that code before its own:

```text
exact: exact needs dyadic angles: the angle 0.3 is not a dyadic multiple of 2π (2πm/2^k, k ≤ 32) [Q500] [J011]
```

As data (the verdict's `refusal`, an MCP tool's error), a refusal carries its
`message`, its `code` (the last it gives), every code it gives in order
(`codes`), the code's `outcome` and its `meaning`. A failure that no code
names (an internal error) has `code` null and the outcome `failed`.

**Stability.** A code never changes meaning once released. New codes are
only ever added; a retired code keeps its row, so a code in an old log or
receipt still means what it meant then.

**Outcomes.**

- `refused`: the job does not run as asked. Change it, as the message says,
  or run it elsewhere.
- `retry`: the host did not take the job now. The same job may be sent
  again later.

An answer's view statements (the answer view layer,
[quantum-answers.md](../../extensions/quantum-answers.md)) have codes of their
own, `J100` to `J112`, each saying what becomes of the statement:

- `dropped`: the statement is left out, and the rest of the answer is drawn.
  An answer's errors, the ones a model is sent back, are its dropped codes.
- `defaulted`: the statement is read as the default the code names.
- `warned`: the statement is drawn as written, with a note that is not sent
  back to the model.

A program in an answer is read by the reader, so its refusals and warnings keep
the reader's codes (`Q…`).

The table is also served as data: `wai_quantum::engine::refusal::codes()` in
Rust, `wai-quantum diagnostics [--json]` on the command line (beside the
reader's codes, under `job_codes`), the `qasm_diagnostics` tool of both MCP
servers (`code` takes either kind), and `engine_diagnostic_codes()` in the
browser engine. A test holds this page to the code's table.

| Code | Outcome | Meaning |
|---|---|---|
| `J001` | refused | A request that is not a job: not a JSON object, or no `qasm` program in it. |
| `J002` | refused | A job that names a provider, sent to a host that reaches none: it runs where the person's credentials are (the command line's `run --provider`, its MCP server's `run_on_provider`, or the desktop app). |
| `J003` | refused | A field of the job that does not read: an observable, an amplitude's bit string, the noise or the method's options (the message names the field and what it takes). |
| `J004` | refused | A job that asks for nothing: give shots, observables or amplitudes. |
| `J005` | refused | More than one job may ask: shots, observables or amplitudes past their limits, or a whole number past ±(2^53 − 1), which JSON readers would not all read alike. |
| `J006` | refused | The compile the job asked for did not complete, or its options do not read (the message says why). |
| `J007` | refused | A set that does not read, or a set sent where one job is read: `programs` not a list of programs or jobs, a `sweep` whose names are not the program's inputs or whose values are not lists of numbers, both given, or more items than a set holds. |
| `J008` | refused | The mitigation the job asked for does not read or cannot be done: no noise model, no observables (no shots, for readout), a program that measures in the middle, more qubits or work than it takes, a device target beside it, or options that do not read (the message says which). |
| `J009` | refused | An error-correction request that does not read or cannot be done: an unknown code or decoder, a decoder the code does not admit, a syndrome or an error that does not fit the code, circuit text or a model that does not read, or sizes past the limits (the message says which). |
| `J010` | refused | A method that does not exist: the methods list names them. |
| `J011` | refused | The method named cannot take this job: a gate it does not hold, more qubits, memory or work than it takes here, or an answer it does not give (noise it cannot take is `J061`); the message says which, and `auto` picks a method that can. A job on `mps` runs under a meter of the bonds it reaches, so this can also come from a job that has started: it stopped where its work passed what a job may take. |
| `J012` | refused | No method takes this job: each method's reason is listed, so the job can be changed to suit one. |
| `J013` | refused | A placement on the fabric (`fabric`) this host cannot honour: no member by that name, no certified accelerator member here, a state or a partition larger than a member holds, a partition count that is not a power of two, or a method or program the fabric's members do not run (the message says which, and what is here). |
| `J020` | refused | An intent that does not read: not one of `distribution`, `equivalent` or `prepares`, a distribution whose outcomes are not the program's bits or whose probabilities do not sum to 1, or a reference program that does not read, or more intents than the host takes. |
| `J021` | refused | A proposed repair that changes a line no diagnostic flags, or adds lines away from one: rejected, and the program left as it was. |
| `J022` | refused | A repair's choices that do not read (`max_iterations`, `dyadic_bits`, `sizes`), or a proposal that is not a program's text. |
| `J030` | retry | The host takes no more from this client for now (submissions in a window, or jobs at once): send it again shortly. |
| `J031` | refused | A job or a check larger than this host takes, its reading included: run it on your own machine, with the command line or its MCP server. |
| `J032` | retry | The host is full (its queue, the checks running at once, or the requests being read, yours or all of them): send it again later. |
| `J033` | refused | A host that takes requests only with one of its API keys: give yours as `Authorization: Bearer <key>`; a key it does not hold is refused the same way. |
| `J034` | refused | An idempotency key (`Idempotency-Key`, or a tool's `idempotency_key`) that does not read, or that this client sent before with another request: a key names one job, so another request needs another key. A key is 1 to 255 visible ASCII characters, and should be unguessable (a UUID, or 128 random bits). |
| `J040` | refused | A pulse run that does not read or cannot be done: a field it does not take, options or device parameters that do not read, a target without the qubit, or a schedule outside the simulator's model (two tones on one qubit at once, a play after its qubit's capture, more levels and qubits than it holds, a frame far from its qubit); the message says which. |
| `J041` | refused | A pulse run whose integration error cannot be stated within its tolerance: a step longer than the generator's norm allows, or a schedule so long that the bound or the rounding passes the tolerance; the message names the steps that would meet it, or says that none does. |
| `J050` | refused | A job's `params` that do not read: not an object of finite numbers, a name the program does not declare as a parameter (`input float`, `input angle`), or a parameter of the program left without a value. |
| `J051` | refused | A gradient that cannot be taken: a differentiation method that does not exist, a parameter the reader cannot carry to the gates (its cause `Q129`), a program that measures in the middle, noise, no Hamiltonian, or more qubits or work than it takes (the message says which). |
| `J052` | refused | An optimisation, a variational eigensolver or a QAOA run that does not read or cannot be done: an unknown optimiser, settings or steps past their limits, a Hamiltonian or a graph that does not read (the message says which). |
| `J053` | refused | An algorithm builder's request that does not read: an unknown algorithm, sizes past its limits, or arguments it does not take (the message says which). |
| `J060` | refused | A compiler pass a request names (`compile.passes`) that this host does not hold: the components list names every method, pass, noise channel and front end here, and no host loads a component from a request. |
| `J061` | refused | A noise channel the method cannot take: a method that models no noise, or a channel the method has no form for (amplitude damping on the stabilizer's Pauli frames, a registered channel on a method that takes only the built-in ones); the message names what does take it. |
| `J062` | refused | A noise channel whose parameters do not read or whose operators fail its validity check: a value outside its range, Kraus operators that are not completely positive and trace preserving (their sum of K†K off the identity), or a Pauli form whose probabilities are negative, do not sum to 1, or are not the channel its operators make (the message says by how much). |
| `J063` | refused | A component the registry does not take: a name its kind holds already (a built-in's among them), a name or version that is empty or not plain text, a descriptor that is not a JSON object, a channel on other than one or two qubits, or a pass whose check states no bound. |
| `J064` | refused | A registered component's answer that breaks the engine's contract: a method's result without an accuracy class it declared, or one that writes a member the engine writes (method, qubits, gates, compiled, repaired, engine, schema, components, receipt, verdict); a pass's gates on qubits the program does not have, or that do not read back; a front end's program that does not read. Nothing it gave is returned. |
| `J065` | refused | An intent on a job whose noise names a registered channel: the intent checks model the built-in channels alone, so the check is refused rather than made against another model. |
| `J070` | refused | A contract that does not read: not an object, a member a contract does not have, an exactness that is no class, a max_cost that is not an amount in decimals and a currency, a deadline or an energy ceiling that is not above zero, providers that is neither never nor allowed, or a job that names a provider while its contract does not allow one (providers: never is the default). |
| `J071` | refused | No route this host can see meets the contract: each route's price or reason is listed, so the contract or the job can be changed. Nothing fell back to a route the contract does not allow. |
| `J072` | refused | A route's result whose accuracy class does not meet the class its job wants: the contract's, or under a contract that names none the class the job keeps. Nothing it gave is returned, since its receipt would not verify. |
| `J073` | refused | A contract where it cannot be honoured: on a set or an item of one (each program runs under its own contract, alone), or on a build with no planner. It is refused rather than read as absent. |
| `J074` | refused | A run stopped at its contract's deadline, by a host that can stop one: the job service's worker, or a provider's job the command line cancels where it waits. The estimate it was planned on was wrong here, and nothing was sealed. |
| `J080` | refused | A write sent to a host with no model to write with: `GET /v1` says under `write` whether a host has one; write the program where the model is, with `wai-quantum-writer write --model DIR TASK.json`. |
| `J081` | refused | A write's task that does not read: a task is an exercise in the course's form (`wai.quantum.exercise/1`), a JSON object with an `intent`, or `cases` that each have one (a case without one takes the task's), so the engine has something to check each program against. |
| `J082` | refused | A write's options that do not read or are out of range: `rounds` a whole number from 0 to 4, `max_new` one from 1 to 4000, and nothing beside `task`, `rounds` and `max_new`. |
| `J090` | refused | A qudit job that does not read: a member it does not take, a gate that is not shift, clock, fourier, csum or phase, a qudit outside the register, a csum on one qudit, a power or a phase outside what the gate takes, or shots, a seed or an amplitude's digits that do not read (the message says which). |
| `J091` | refused | A qudit job in a dimension whose roots of unity the engine does not hold: d is 2, 3, 4 or 6, whose roots have the coordinates 0, ±1, ±1/2 and ±√3/2; every other dimension is refused rather than given roots from a float or a series. |
| `J092` | refused | A qudit job larger than one job may be: more amplitudes (d to the power of the qudits) than a register holds, more gates, shots or amplitudes asked for than a job takes, or more work than a job may do (the message gives each figure and its limit). |
| `J100` | dropped | A line of an answer that is not a statement (`name = View(...)`), a program (a fenced `qasm` block with its name), a comment or a marker: left out. |
| `J101` | dropped | A view the answer layer does not have: left out (the views are listed in the layer's specification). |
| `J102` | dropped | An `@` call the engine does not have: the statement is left out. |
| `J103` | dropped | A view or an `@` call without an argument it requires: the statement is left out. |
| `J104` | dropped | An argument of the wrong kind, such as a number where a view takes the engine's call (a number in a view comes from the engine), or a program where a list is taken: the statement is left out. |
| `J105` | warned | More arguments than a view or an `@` call takes: the extra ones are left out. |
| `J106` | dropped | A name no statement declares, or one whose statement was left out (a program the reader refused, say): the statement that names it is left out. |
| `J107` | defaulted | No `root = Answer([...])`: the views are drawn in the order they are written. |
| `J108` | dropped | The answer ends inside a program or a statement: the unfinished part is left out. |
| `J109` | dropped | Statements that name each other in a cycle: each is left out. |
| `J110` | warned | A name declared again: the later declaration stands, which is how an answer is edited. |
| `J111` | warned | A number written in a view's text, which no engine call gave: let a view show it. |
| `J112` | warned | A statement the root does not reach: it is not drawn. |