> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# v0.4 Error Codes

> HTTP error responses and job failure codes returned by the IonQ v0.4 API

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:

```javascript theme={null}
{
    '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 [support@ionq.co](mailto:support@ionq.co)                                     |
| 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](https://status.ionq.co) |
| Service Unavailable   | 503         | Indicative of a service outage - please check [status.ionq.co](https://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](/api-reference/v0.4/jobs/get-job)) includes a `failure` field describing what went wrong:

```javascript theme={null}
{
    '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                                                                                       |

***