v0.4 Error Codes

When a request fails, the API will respond with an appropriate 4xx or 5xx error in the following format in the body of the response:

{
    'error': 'Error Name',
    'message': 'A description of the specific error conditions.',
    'statusCode': 400
}

Error	Status code	Description
Bad Request	400	Generic request error. The message should indicate the specific parameter which was invalid.
Unauthorized	401	The request failed to authenticate the supplied API key
Forbidden	403	The supplied API key failed authorization for the requested resource
Not Found	404	The specified resource does not exist or could not be found.
Too Many Requests	429	The request was rate limited. To get a higher rate limit, please reach out to [email protected]
Internal Server Error	500	A service was unexpectedly offline, unavailable, or failed in an unknown manner.
Bad Gateway	502	This can be caused by misbehaving proxies or by service issues. These can be retried, and downtime can be found on status.ionq.co
Service Unavailable	503	Indicative of a service outage - please check status.ionq.co

For 400 Bad Request responses, the body may also include a validation object with details about which part of the request failed validation. Responses generated at the gateway level rather than by the API itself (429, 502, and 503) may not include the JSON body shown above.

Job Errors

When a job fails, its status becomes failed and the job object (API reference) includes a failure field describing what went wrong:

{
    'id': 'aa54e783-13d2-46e0-56b2-e6d29b7c8e0f',
    'status': 'failed',
    'failure': {
        'code': 'TooManyShots',
        'message': 'A description of the specific failure conditions.'
    },
    ...
}

The failure.code field will be one of the following:

Error	Description
CompilationError	Generic failure in our compilation service
ContractExpiredError	The billing service shows that the contract governing the key being used has expired
DebiasingError	Unknown execution error when using debiasing (an IonQ-provided error mitigation technique)
InternalError	An unattributable internal error
InvalidInput	The job input failed validation. The message should indicate the specific part of the input which was invalid
NotEnoughQubits	The backend you are submitting to has fewer qubits than this job requires
OptimizationError	Generic error in our optimization service
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
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.
QuantumComputerError	Generic failure that occurred while the job was being processed on-QPU
QuotaExhaustedError	The billing system shows that your user, project, or organization has an inadequate credit balance to run this job
SimulationError	Generic failure in our simulation service
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
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
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
TooManyControls	The job submitted includes a multi-control gate with more control qubits than allowed (more than 7)
TooManyGates	Preflight error of a specific type: the job submitted includes more gates per circuit than the target backend allows
TooManyShots	Preflight error of a specific type: the job submitted requested more shots than the target backend allows
UnknownBillingError	Unknown error related to but not originating from our billing service. This most often means the service is briefly unavailable for some reason.
UnsupportedGate	Preflight error of a specific type: the job submitted uses a gate that the target backend does not allow

IonQ v0.4 API

Jobs

Sessions

Backends

Utilities

Schemas

Job Errors

​Job Errors

Job Errors