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). What is asked of a program has codes of its own (J…): the request, the method, an intent, a repair, and the host that runs the job. A refusal reads, on every surface:

stabilizer needs a Clifford circuit: … [J011]

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

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) 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, noise it does not model, or an answer it does not give; the message says which, and auto picks a method that can.
J012	refused	No method takes this job: each method's reason is listed, so the job can be changed to suit one.
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.
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: run it on your own machine, with the command line or its MCP server.
J032	retry	The host is full (its queue, or the checks running at once): 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.
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.