Error reference
Every error a Qollab run can return, what it means, and what to do about it: IonQ job failures, API responses, the Qiskit provider, and the playground itself.
Errors reach you from three places: IonQ's service, the Qiskit provider that talks to it, and the playground itself.
The job-failure and API-response tables below are reproduced from IonQ's own reference, IonQ's v0.4 error codes, the source of truth for both. Crawled 2026-09-09.
Job failures on IonQ hardware
| Code | What IonQ says | What to do on Qollab |
|---|---|---|
CompilationError | "Generic failure in our compilation service" | Run the same circuit on the built-in simulator first. If it passes there, simplify the circuit and resubmit. |
ContractExpiredError | "The billing service shows that the contract governing the key being used has expired" | Nothing you can fix from the editor: this is the platform's IonQ contract, not your account. Report it. |
DebiasingError | "Unknown execution error when using debiasing (an IonQ-provided error mitigation technique)" | Debiasing is IonQ's own error mitigation and is on by default. It is switched off in code when you submit the job, not in a settings panel. See the IonQ hardware lesson, which shows exactly that call. |
InternalError | "An unattributable internal error" | Retry once. If it repeats, check status.ionq.co. |
InvalidInput | "The job input failed validation. The message should indicate the specific part of the input which was invalid" | The message names the part that failed. Usually a gate argument the backend will not take. |
NotEnoughQubits | "The backend you are submitting to has fewer qubits than this job requires" | Your circuit asks for more qubits than the backend has. Check the qubit column on Compute backends and pick a bigger one or shrink the circuit. |
OptimizationError | "Generic error in our optimization service" | Retry once, then simplify the circuit. |
PreflightError | "Generic error during preflight checks. This most often occurs when the input circuit is syntax checked and includes malformed gates, commands, formats, or similar" | Caught before anything ran, so it cost nothing. Run on the built-in simulator, which catches the same class of problem instantly. |
QuantumCircuitComplexityError | "This failure occurs when the coherent program used to execute this circuit cannot be feasibly run on the system targeted. Reducing the number of gates requested can often resolve this issue." | Too many gates to hold coherently on that machine. Reduce the gate count, or run it on a simulator where depth is free. |
QuantumComputerError | "Generic failure that occurred while the job was being processed on-QPU" | The job reached the machine and failed there. Retry, and report it if credits were spent. |
QuotaExhaustedError | "The billing system shows that your user, project, or organization has an inadequate credit balance to run this job" | Out of credits. See How credits work. |
SimulationError | "Generic failure in our simulation service" | This is IonQ's cloud simulator, not the local one. Try the built-in simulator, which runs in your browser. |
SimulationTimeout | "Timeout error in our simulation service. This is most commonly caused by simulations that are too large for the service to simulate before hitting our runaway process timeout" | The simulation was too large for IonQ's service. Fewer qubits or fewer shots, or use a local simulator. |
SystemCancel | "A member of IonQ staff has manually cancelled your job. This most often occurs as a result of a customer request, but can sometimes represent manual resolution of an unknown failure mode" | Cancelled by IonQ staff rather than by anything in your circuit. Resubmit. |
TooLongPredictedExecutionTime | "Preflight error of a specific type: the predicted execution time for the circuit was longer than the single-job timeout duration for a given backend" | Predicted runtime is over the backend's single-job limit. Lower shots first, since runtime scales with it. |
TooManyControls | "The job submitted includes a multi-control gate with more control qubits than allowed (more than 7)" | A multi-control gate with more than seven controls. Decompose it into smaller gates. |
TooManyGates | "Preflight error of a specific type: the job submitted includes more gates per circuit than the target backend allows" | Over the backend's per-circuit gate limit. Note that transpiling can add gates, so the count you wrote is not the count submitted. |
TooManyShots | "Preflight error of a specific type: the job submitted requested more shots than the target backend allows" | Lower the shots argument on your run. |
UnknownBillingError | "Unknown error related to but not originating from our billing service. This most often means the service is briefly unavailable for some reason." | Usually a brief billing service blip. Retry. |
UnsupportedGate | "Preflight error of a specific type: the job submitted uses a gate that the target backend does not allow" | The gate is not in that backend's set. Transpile for the target, or swap the gate. See Compilation and native gates in IonQ's docs. |
API responses
On Qollab the IonQ API key belongs to the platform, not to you. A 401 or 403 here is never something you can fix by rotating a key, which is exactly what IonQ's own wording would lead you to try.
| Status | What IonQ says | What it means on Qollab |
|---|---|---|
400 Bad Request | "Generic request error. The message should indicate the specific parameter which was invalid." | A malformed job. |
401 Unauthorized | "The request failed to authenticate the supplied API key" | Report it. |
403 Forbidden | "The supplied API key failed authorization for the requested resource" | Report it. |
404 Not Found | "The specified resource does not exist or could not be found." | Report it. |
429 Too Many Requests | "The request was rate limited. To get a higher rate limit, please reach out to support@ionq.co" | Retry shortly. The key belongs to Qollab, not to you, so report it here rather than contacting IonQ. |
500 Internal Server Error | "A service was unexpectedly offline, unavailable, or failed in an unknown manner." | Check status.ionq.co and retry. |
502 Bad Gateway | "This can be caused by misbehaving proxies or by service issues. These can be retried, and downtime can be found on status.ionq.co" | Check status.ionq.co and retry. |
503 Service Unavailable | "Indicative of a service outage - please check status.ionq.co" | Check status.ionq.co and retry. |
Errors from the Qiskit provider
Neither vendor documents this section, because it belongs to the client library sitting between them: qiskit-ionq.
The one real case is an AttributeError raised inside qiskit-ionq while a job is being submitted. Quantum Garden's author traced it: the provider crashes parsing an IonQ error response that arrived as a plain string rather than an object. Its own failure then replaces IonQ's message, so the real cause never reaches you. It is usually authentication or an exhausted quota. Check credits first.
Quantum Garden handles it in published code:
try:
job = backend.run(circuit, shots=shots)
except AttributeError as e:
# qiskit-ionq bug: SDK crashes parsing error responses that are
# plain strings instead of dicts. The real error is usually
# an auth failure or quota issue.
print(f"qiskit-ionq SDK parsing bug — check API key and backend target: {e}")
return
except Exception as e:
print(f"Job submission failed: {e}")
return
▶ Run on QollabBackend
The general defence is wrapping the submit call in try. Entangled Body's three-tier fallback is a worked example.
The playground itself
| Symptom | What to do |
|---|---|
| JSPI compatibility warning | See the FAQ for the about:config fix. |
| Out of credits | See How credits work. |
| A red traceback in the console | Your Python, not the machine. Fix the line it points to and run again. |
Related
Stay in the loop.
Get the latest tutorials, demos, and project showcases straight to your inbox. No noise, just the good stuff.