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

# Errors

> Complete list of error codes with explanations and troubleshooting tips

OneBalance uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the `5xx` range indicate an error with OneBalance's servers.

## HTTP Status Codes

| Status Code        | Type              | Description                                                                                      |
| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------ |
| 200                | OK                | Everything worked as expected.                                                                   |
| 400                | Bad Request       | The request was unacceptable, often due to missing a required parameter.                         |
| 401                | Unauthorized      | No valid API key provided.                                                                       |
| 402                | Request Failed    | The parameters were valid but the request failed.                                                |
| 403                | Forbidden         | The API key doesn't have permissions to perform the request.                                     |
| 404                | Not Found         | The requested resource doesn't exist.                                                            |
| 429                | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
| 500, 502, 503, 504 | Server Errors     | Something went wrong on OneBalance's end.                                                        |

## Quote Execution Failures

While HTTP status codes indicate API request success/failure, quote executions can fail for business logic reasons even when the API request succeeds (returns 200). When a quote execution fails, it will be marked as `REFUNDED` and include a `failReason` field explaining why.

### Understanding the Difference

* **HTTP Errors** (4xx/5xx): Issues with the API request itself (authentication, malformed requests, server errors)
* **Execution Failures**: Business logic failures where the quote couldn't be completed (insufficient balance, slippage, etc.)

<Info>
  For a complete list of execution failure codes with detailed explanations and troubleshooting steps, see [Error Codes](/api-reference/error-codes).
</Info>

## Error Response Format

Both `400` and `500` level errors return a JSON object in the response body, containing specific attributes detailing the error.

| Name       | Type   | Description                                                                                                                                              |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| error      | string | A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not\_found." |
| message    | string | A message providing additional information about the error, including details to help resolve it when possible.                                          |
| statusCode | number | HTTP status code.                                                                                                                                        |
| timestamp  | string | Timestamp of the error.                                                                                                                                  |
| path       | string | Path of the request that caused the error.                                                                                                               |

## Example Error Response

HTTP/1.1 401 Unauthorized

```json Unauthorized theme={null}
{
  "error": "UnauthorizedException",
  "message": "Invalid or missing API key",
  "statusCode": 401,
  "timestamp": "2024-12-18T14:38:24.793Z",
  "path": "/api/xxx/xxx"
}
```

## Error Handling Best Practices

* Always check for error responses in your API integrations
* Use the `statusCode` to determine the type of error
* Look at the `message` field for specific details on how to resolve the issue
* For refunded quotes, check the `failReason` field and implement appropriate retry logic
* Include the error `id` when using the **Intercom chat widget** or contacting support about any API issues
* See [Error Codes](/api-reference/error-codes) for handling specific execution failure scenarios