[{"data":1,"prerenderedAt":801},["ShallowReactive",2],{"blog-post-docs\u002Ferror-reference":3,"sibling-dives-docs\u002Ferror-reference":799,"learn-track-docs\u002Ferror-reference":800},{"id":4,"title":5,"authors":6,"body":7,"breadcrumb":6,"builders":6,"byline":6,"category":782,"categoryName":783,"challenge":6,"courseAuthor":6,"courseLead":6,"dek":6,"description":784,"draft":785,"extension":786,"eyebrow":6,"featured":785,"finish":6,"fork":6,"hero":6,"heroAlt":6,"heroCta":6,"heroImage":6,"homepageFeatured":785,"kind":787,"lessonCount":6,"meta":788,"navigation":789,"newsItems":6,"next":6,"ogImage":6,"order":546,"outcomes":6,"path":790,"publishDate":791,"readingTime":6,"related":792,"relatedProjects":6,"seo":793,"stem":796,"tags":797,"track":6,"trackName":6,"__hash__":798},"blog\u002Fblog\u002Flearn\u002Fdocs\u002Ferror-reference.md","Error reference",null,{"type":8,"value":9,"toc":775},"minimark",[10,14,23,28,343,347,358,490,494,500,510,517,682,694,698,747,751,771],[11,12,13],"p",{},"Errors reach you from three places: IonQ's service, the Qiskit provider that talks to it, and the playground itself.",[11,15,16,17,22],{},"The job-failure and API-response tables below are reproduced from IonQ's own reference, ",[18,19,21],"a",{"href":20},"https:\u002F\u002Fdocs.ionq.com\u002Fapi-reference\u002Fv0.4\u002Ferror-codes","IonQ's v0.4 error codes",", the source of truth for both. Crawled 2026-09-09.",[24,25,27],"h2",{"id":26},"job-failures-on-ionq-hardware","Job failures on IonQ hardware",[29,30,31,47],"table",{},[32,33,34],"thead",{},[35,36,37,41,44],"tr",{},[38,39,40],"th",{},"Code",[38,42,43],{},"What IonQ says",[38,45,46],{},"What to do on Qollab",[48,49,50,65,78,96,114,127,145,158,171,184,197,214,227,240,253,270,283,296,312,325],"tbody",{},[35,51,52,59,62],{},[53,54,55],"td",{},[56,57,58],"code",{},"CompilationError",[53,60,61],{},"\"Generic failure in our compilation service\"",[53,63,64],{},"Run the same circuit on the built-in simulator first. If it passes there, simplify the circuit and resubmit.",[35,66,67,72,75],{},[53,68,69],{},[56,70,71],{},"ContractExpiredError",[53,73,74],{},"\"The billing service shows that the contract governing the key being used has expired\"",[53,76,77],{},"Nothing you can fix from the editor: this is the platform's IonQ contract, not your account. Report it.",[35,79,80,85,88],{},[53,81,82],{},[56,83,84],{},"DebiasingError",[53,86,87],{},"\"Unknown execution error when using debiasing (an IonQ-provided error mitigation technique)\"",[53,89,90,91,95],{},"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 ",[18,92,94],{"href":93},"\u002Flearn\u002Fquantum-computing-with-python\u002Fionq-hardware","IonQ hardware lesson",", which shows exactly that call.",[35,97,98,103,106],{},[53,99,100],{},[56,101,102],{},"InternalError",[53,104,105],{},"\"An unattributable internal error\"",[53,107,108,109,113],{},"Retry once. If it repeats, check ",[18,110,112],{"href":111},"https:\u002F\u002Fstatus.ionq.co","status.ionq.co",".",[35,115,116,121,124],{},[53,117,118],{},[56,119,120],{},"InvalidInput",[53,122,123],{},"\"The job input failed validation. The message should indicate the specific part of the input which was invalid\"",[53,125,126],{},"The message names the part that failed. Usually a gate argument the backend will not take.",[35,128,129,134,137],{},[53,130,131],{},[56,132,133],{},"NotEnoughQubits",[53,135,136],{},"\"The backend you are submitting to has fewer qubits than this job requires\"",[53,138,139,140,144],{},"Your circuit asks for more qubits than the backend has. Check the qubit column on ",[18,141,143],{"href":142},"\u002Flearn\u002Fdocs\u002Fcompute-backends","Compute backends"," and pick a bigger one or shrink the circuit.",[35,146,147,152,155],{},[53,148,149],{},[56,150,151],{},"OptimizationError",[53,153,154],{},"\"Generic error in our optimization service\"",[53,156,157],{},"Retry once, then simplify the circuit.",[35,159,160,165,168],{},[53,161,162],{},[56,163,164],{},"PreflightError",[53,166,167],{},"\"Generic error during preflight checks. This most often occurs when the input circuit is syntax checked and includes malformed gates, commands, formats, or similar\"",[53,169,170],{},"Caught before anything ran, so it cost nothing. Run on the built-in simulator, which catches the same class of problem instantly.",[35,172,173,178,181],{},[53,174,175],{},[56,176,177],{},"QuantumCircuitComplexityError",[53,179,180],{},"\"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.\"",[53,182,183],{},"Too many gates to hold coherently on that machine. Reduce the gate count, or run it on a simulator where depth is free.",[35,185,186,191,194],{},[53,187,188],{},[56,189,190],{},"QuantumComputerError",[53,192,193],{},"\"Generic failure that occurred while the job was being processed on-QPU\"",[53,195,196],{},"The job reached the machine and failed there. Retry, and report it if credits were spent.",[35,198,199,204,207],{},[53,200,201],{},[56,202,203],{},"QuotaExhaustedError",[53,205,206],{},"\"The billing system shows that your user, project, or organization has an inadequate credit balance to run this job\"",[53,208,209,210,113],{},"Out of credits. See ",[18,211,213],{"href":212},"\u002Flearn\u002Fdocs\u002Fhow-credits-work","How credits work",[35,215,216,221,224],{},[53,217,218],{},[56,219,220],{},"SimulationError",[53,222,223],{},"\"Generic failure in our simulation service\"",[53,225,226],{},"This is IonQ's cloud simulator, not the local one. Try the built-in simulator, which runs in your browser.",[35,228,229,234,237],{},[53,230,231],{},[56,232,233],{},"SimulationTimeout",[53,235,236],{},"\"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\"",[53,238,239],{},"The simulation was too large for IonQ's service. Fewer qubits or fewer shots, or use a local simulator.",[35,241,242,247,250],{},[53,243,244],{},[56,245,246],{},"SystemCancel",[53,248,249],{},"\"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\"",[53,251,252],{},"Cancelled by IonQ staff rather than by anything in your circuit. Resubmit.",[35,254,255,260,263],{},[53,256,257],{},[56,258,259],{},"TooLongPredictedExecutionTime",[53,261,262],{},"\"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\"",[53,264,265,266,269],{},"Predicted runtime is over the backend's single-job limit. Lower ",[56,267,268],{},"shots"," first, since runtime scales with it.",[35,271,272,277,280],{},[53,273,274],{},[56,275,276],{},"TooManyControls",[53,278,279],{},"\"The job submitted includes a multi-control gate with more control qubits than allowed (more than 7)\"",[53,281,282],{},"A multi-control gate with more than seven controls. Decompose it into smaller gates.",[35,284,285,290,293],{},[53,286,287],{},[56,288,289],{},"TooManyGates",[53,291,292],{},"\"Preflight error of a specific type: the job submitted includes more gates per circuit than the target backend allows\"",[53,294,295],{},"Over the backend's per-circuit gate limit. Note that transpiling can add gates, so the count you wrote is not the count submitted.",[35,297,298,303,306],{},[53,299,300],{},[56,301,302],{},"TooManyShots",[53,304,305],{},"\"Preflight error of a specific type: the job submitted requested more shots than the target backend allows\"",[53,307,308,309,311],{},"Lower the ",[56,310,268],{}," argument on your run.",[35,313,314,319,322],{},[53,315,316],{},[56,317,318],{},"UnknownBillingError",[53,320,321],{},"\"Unknown error related to but not originating from our billing service. This most often means the service is briefly unavailable for some reason.\"",[53,323,324],{},"Usually a brief billing service blip. Retry.",[35,326,327,332,335],{},[53,328,329],{},[56,330,331],{},"UnsupportedGate",[53,333,334],{},"\"Preflight error of a specific type: the job submitted uses a gate that the target backend does not allow\"",[53,336,337,338,342],{},"The gate is not in that backend's set. Transpile for the target, or swap the gate. See ",[18,339,341],{"href":340},"https:\u002F\u002Fdocs.ionq.com\u002Fsdks\u002Fqiskit\u002Fnative-gates-qiskit","Compilation and native gates"," in IonQ's docs.",[24,344,346],{"id":345},"api-responses","API responses",[11,348,349,350,353,354,357],{},"On Qollab the IonQ API key belongs to the platform, not to you. A ",[56,351,352],{},"401"," or ",[56,355,356],{},"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.",[29,359,360,372],{},[32,361,362],{},[35,363,364,367,369],{},[38,365,366],{},"Status",[38,368,43],{},[38,370,371],{},"What it means on Qollab",[48,373,374,387,400,412,424,442,458,474],{},[35,375,376,381,384],{},[53,377,378],{},[56,379,380],{},"400 Bad Request",[53,382,383],{},"\"Generic request error. The message should indicate the specific parameter which was invalid.\"",[53,385,386],{},"A malformed job.",[35,388,389,394,397],{},[53,390,391],{},[56,392,393],{},"401 Unauthorized",[53,395,396],{},"\"The request failed to authenticate the supplied API key\"",[53,398,399],{},"Report it.",[35,401,402,407,410],{},[53,403,404],{},[56,405,406],{},"403 Forbidden",[53,408,409],{},"\"The supplied API key failed authorization for the requested resource\"",[53,411,399],{},[35,413,414,419,422],{},[53,415,416],{},[56,417,418],{},"404 Not Found",[53,420,421],{},"\"The specified resource does not exist or could not be found.\"",[53,423,399],{},[35,425,426,431,439],{},[53,427,428],{},[56,429,430],{},"429 Too Many Requests",[53,432,433,434,438],{},"\"The request was rate limited. To get a higher rate limit, please reach out to ",[18,435,437],{"href":436},"mailto:support@ionq.co","support@ionq.co","\"",[53,440,441],{},"Retry shortly. The key belongs to Qollab, not to you, so report it here rather than contacting IonQ.",[35,443,444,449,452],{},[53,445,446],{},[56,447,448],{},"500 Internal Server Error",[53,450,451],{},"\"A service was unexpectedly offline, unavailable, or failed in an unknown manner.\"",[53,453,454,455,457],{},"Check ",[18,456,112],{"href":111}," and retry.",[35,459,460,465,470],{},[53,461,462],{},[56,463,464],{},"502 Bad Gateway",[53,466,467,468,438],{},"\"This can be caused by misbehaving proxies or by service issues. These can be retried, and downtime can be found on ",[18,469,112],{"href":111},[53,471,454,472,457],{},[18,473,112],{"href":111},[35,475,476,481,486],{},[53,477,478],{},[56,479,480],{},"503 Service Unavailable",[53,482,483,484,438],{},"\"Indicative of a service outage - please check ",[18,485,112],{"href":111},[53,487,454,488,457],{},[18,489,112],{"href":111},[24,491,493],{"id":492},"errors-from-the-qiskit-provider","Errors from the Qiskit provider",[11,495,496,497,113],{},"Neither vendor documents this section, because it belongs to the client library sitting between them: ",[56,498,499],{},"qiskit-ionq",[11,501,502,503,506,507,509],{},"The one real case is an ",[56,504,505],{},"AttributeError"," raised inside ",[56,508,499],{}," 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.",[11,511,512,516],{},[18,513,515],{"href":514},"\u002Fu\u002FAmberPincar\u002Fquantum-garden","Quantum Garden"," handles it in published code:",[518,519,522],"code-block",{"name":520,"run-href":514,"tag":521},"quantum_garden.py","Python · excerpt",[523,524,529],"pre",{"className":525,"code":526,"language":527,"meta":528,"style":528},"language-python shiki shiki-themes one-dark-pro","  try:\n    job = backend.run(circuit, shots=shots)\n  except AttributeError as e:\n    # qiskit-ionq bug: SDK crashes parsing error responses that are\n    # plain strings instead of dicts. The real error is usually\n    # an auth failure or quota issue.\n    print(f\"qiskit-ionq SDK parsing bug — check API key and backend target: {e}\")\n    return\n  except Exception as e:\n    print(f\"Job submission failed: {e}\")\n    return\n","python","",[56,530,531,544,572,587,594,600,606,637,643,655,677],{"__ignoreMap":528},[532,533,536,540],"span",{"class":534,"line":535},"line",1,[532,537,539],{"class":538},"seHd6","  try",[532,541,543],{"class":542},"sn6KH",":\n",[532,545,547,550,554,557,561,564,567,569],{"class":534,"line":546},2,[532,548,549],{"class":542},"    job ",[532,551,553],{"class":552},"sjrmR","=",[532,555,556],{"class":542}," backend.",[532,558,560],{"class":559},"sVbv2","run",[532,562,563],{"class":542},"(circuit, ",[532,565,268],{"class":566},"s_ZVi",[532,568,553],{"class":552},[532,570,571],{"class":542},"shots)\n",[532,573,575,578,581,584],{"class":534,"line":574},3,[532,576,577],{"class":538},"  except",[532,579,580],{"class":542}," AttributeError ",[532,582,583],{"class":538},"as",[532,585,586],{"class":542}," e:\n",[532,588,590],{"class":534,"line":589},4,[532,591,593],{"class":592},"sV9Aq","    # qiskit-ionq bug: SDK crashes parsing error responses that are\n",[532,595,597],{"class":534,"line":596},5,[532,598,599],{"class":592},"    # plain strings instead of dicts. The real error is usually\n",[532,601,603],{"class":534,"line":602},6,[532,604,605],{"class":592},"    # an auth failure or quota issue.\n",[532,607,609,612,615,618,622,626,629,632,634],{"class":534,"line":608},7,[532,610,611],{"class":552},"    print",[532,613,614],{"class":542},"(",[532,616,617],{"class":538},"f",[532,619,621],{"class":620},"subq3","\"qiskit-ionq SDK parsing bug — check API key and backend target: ",[532,623,625],{"class":624},"sVC51","{",[532,627,628],{"class":542},"e",[532,630,631],{"class":624},"}",[532,633,438],{"class":620},[532,635,636],{"class":542},")\n",[532,638,640],{"class":534,"line":639},8,[532,641,642],{"class":538},"    return\n",[532,644,646,648,651,653],{"class":534,"line":645},9,[532,647,577],{"class":538},[532,649,650],{"class":542}," Exception ",[532,652,583],{"class":538},[532,654,586],{"class":542},[532,656,658,660,662,664,667,669,671,673,675],{"class":534,"line":657},10,[532,659,611],{"class":552},[532,661,614],{"class":542},[532,663,617],{"class":538},[532,665,666],{"class":620},"\"Job submission failed: ",[532,668,625],{"class":624},[532,670,628],{"class":542},[532,672,631],{"class":624},[532,674,438],{"class":620},[532,676,636],{"class":542},[532,678,680],{"class":534,"line":679},11,[532,681,642],{"class":538},[11,683,684,685,688,689,693],{},"The general defence is wrapping the submit call in ",[56,686,687],{},"try",". ",[18,690,692],{"href":691},"\u002Fu\u002Flukeshim\u002Fentangled-body","Entangled Body's three-tier fallback"," is a worked example.",[24,695,697],{"id":696},"the-playground-itself","The playground itself",[29,699,700,710],{},[32,701,702],{},[35,703,704,707],{},[38,705,706],{},"Symptom",[38,708,709],{},"What to do",[48,711,712,729,739],{},[35,713,714,717],{},[53,715,716],{},"JSPI compatibility warning",[53,718,719,720,724,725,728],{},"See the ",[18,721,723],{"href":722},"\u002Flearn\u002Fdocs\u002Ffaq#the-playground-shows-a-compatibility-warning","FAQ"," for the ",[56,726,727],{},"about:config"," fix.",[35,730,731,734],{},[53,732,733],{},"Out of credits",[53,735,736,737,113],{},"See ",[18,738,213],{"href":212},[35,740,741,744],{},[53,742,743],{},"A red traceback in the console",[53,745,746],{},"Your Python, not the machine. Fix the line it points to and run again.",[24,748,750],{"id":749},"related","Related",[752,753,754,761,765],"ul",{},[755,756,757],"li",{},[18,758,760],{"href":759},"\u002Flearn\u002Fdocs\u002Ffaq","Troubleshooting and FAQ",[755,762,763],{},[18,764,143],{"href":142},[755,766,767],{},[18,768,770],{"href":769},"\u002Flearn\u002Fdocs\u002Fwhy-your-results-look-wrong","Why your results look wrong",[772,773,774],"style",{},"html pre.shiki code .seHd6, html code.shiki .seHd6{--shiki-default:#C678DD}html pre.shiki code .sn6KH, html code.shiki .sn6KH{--shiki-default:#ABB2BF}html pre.shiki code .sjrmR, html code.shiki .sjrmR{--shiki-default:#56B6C2}html pre.shiki code .sVbv2, html code.shiki .sVbv2{--shiki-default:#61AFEF}html pre.shiki code .s_ZVi, html code.shiki .s_ZVi{--shiki-default:#E06C75;--shiki-default-font-style:italic}html pre.shiki code .sV9Aq, html code.shiki .sV9Aq{--shiki-default:#7F848E;--shiki-default-font-style:italic}html pre.shiki code .subq3, html code.shiki .subq3{--shiki-default:#98C379}html pre.shiki code .sVC51, html code.shiki .sVC51{--shiki-default:#D19A66}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":528,"searchDepth":546,"depth":546,"links":776},[777,778,779,780,781],{"id":26,"depth":546,"text":27},{"id":345,"depth":546,"text":346},{"id":492,"depth":546,"text":493},{"id":696,"depth":546,"text":697},{"id":749,"depth":546,"text":750},"troubleshooting","Troubleshooting","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.",false,"md","doc",{},true,"\u002Fblog\u002Flearn\u002Fdocs\u002Ferror-reference","2026-09-09",[],{"title":794,"description":795},"Error reference · Qollab docs","What each Qollab and IonQ error means and how to fix it, including job failure codes, API responses, and Qiskit provider errors.","blog\u002Flearn\u002Fdocs\u002Ferror-reference",[],"FA_z0F4rtyRsCXsvY0Bt_bfl0lsF6ASPNYEAS7_yfV8",[],[],1788974866150]