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

# Error handling

> Understand Breet API error responses, HTTP status codes, and how to handle common error scenarios in your integration.

## Response format

### Success responses

Successful requests return a JSON object with the following shape:

```json theme={null}
{
  "success": true,
  "message": "wallets retrieved successfully",
  "data": { ... },
  "meta": { ... }
}
```

| Field     | Type            | Description                                                                      |
| --------- | --------------- | -------------------------------------------------------------------------------- |
| `success` | boolean         | Always `true` for successful requests.                                           |
| `message` | string          | A human-readable description of the result.                                      |
| `data`    | object or array | The response payload. May be an object, an array, or empty `{}`.                 |
| `meta`    | object          | Metadata such as [pagination](/pagination) info. Empty `{}` when not applicable. |

### Error responses

Failed requests return a JSON object with the following shape:

```json theme={null}
{
  "success": false,
  "message": "TRX_TEST for your-wallet-label already exists in your wallets",
  "meta": {},
  "errors": [],
  "data": {}
}
```

| Field     | Type    | Description                                      |
| --------- | ------- | ------------------------------------------------ |
| `success` | boolean | Always `false` for failed requests.              |
| `message` | string  | A human-readable description of what went wrong. |
| `errors`  | array   | Additional error details when available.         |
| `meta`    | object  | Empty for error responses.                       |
| `data`    | object  | Empty for error responses.                       |

<Warning>
  Not all error responses include every field. See the exceptions for **429** and **500** below.
</Warning>

## Common error scenarios

### 400 - Bad request

Returned when the request is invalid or violates a business rule.

**Duplicate wallet label:**

```json theme={null}
{
  "success": false,
  "message": "TRX_TEST for your-wallet-label already exists in your wallets",
  "meta": {},
  "errors": [],
  "data": {}
}
```

This occurs when you attempt to generate a wallet address with a label that already exists for the same asset.

### 401 - Unauthorized

Returned when authentication credentials are missing or invalid. Ensure you are sending the correct `x-app-id` and `x-app-secret` headers, and that the `X-Breet-Env` header is set to either `development` or `production`. See the [quickstart](/quickstart) for how to obtain and configure your credentials.

### 403 - Forbidden

Returned when your account does not have permission to perform the requested action.

```json theme={null}
{
  "success": false,
  "message": "access is forbidden",
  "meta": {},
  "errors": [],
  "data": {}
}
```

### 404 - Not found

Returned when the requested resource does not exist.

**Wallet not found:**

```json theme={null}
{
  "success": false,
  "message": "wallet not found",
  "meta": {},
  "errors": [],
  "data": {}
}
```

**Transaction not found:**

```json theme={null}
{
  "success": false,
  "message": "transaction not found",
  "meta": {},
  "errors": [],
  "data": {}
}
```

### 409 - Conflict

Returned when the request conflicts with the current state of a resource, such as attempting to create a resource that already exists.

### 422 - Unprocessable entity

Returned when the request is well-formed but cannot be processed due to a validation or business logic constraint.

```json theme={null}
{
  "success": false,
  "message": "wallet does not have a bank",
  "meta": {},
  "errors": [],
  "data": {}
}
```

This commonly occurs when enabling [auto-settlement](/auto-settlement) on a wallet that doesn't have a linked bank account.

### 429 - Too many requests

Returned when you exceed the [rate limit](/rate-limiting). Back off and retry after the time indicated in the `Retry-After` response header (value in seconds).

<Info>
  The 429 response body does **not** follow the standard error shape. It only returns a `message` field:

  ```json theme={null}
  {
    "message": "Too many requests. Please try again later."
  }
  ```

  Your error handling should account for this exception.
</Info>

### 500 - Internal server error

Returned when an unexpected error occurs on the server. The response body includes `success`, `message`, `meta`, and `errors`, but does **not** include a `data` field:

```json theme={null}
{
  "success": false,
  "message": "something went wrong!",
  "meta": {},
  "errors": []
}
```

For 500 errors, implement retry logic with exponential backoff.

## Best practices

* Always check the `success` field before processing the response.
* Use the `message` field for logging and debugging. Do not rely on exact message text for control flow, as messages may change.
* Handle `4xx` errors gracefully in your application with appropriate user feedback.
* For `429` errors, read the `Retry-After` header to determine how long to wait before retrying.
* For `5xx` errors, implement retry logic with exponential backoff.