Error handling

Response format

Success responses

Successful requests return a JSON object with the following shape:

{
  "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 info. Empty `{}` when not applicable.

Error responses

Failed requests return a JSON object with the following shape:

{
  "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	Field-level validation details. Empty for business-rule errors.
`meta`	object	Empty for error responses.
`data`	object	Empty for error responses.

Field-level validation errors

When a request fails validation, the response returns 422, a message of validation errors, and one entry in errors per problem:

{
  "success": false,
  "message": "validation errors",
  "errors": [
    { "message": "LTC does not support a network", "field": "network", "location": "body" }
  ],
  "meta": {},
  "data": {}
}

A single bad field can produce several entries. Omitting both amount and cryptoAmount, for example, returns eight, because every rule on both fields reports separately. Read the first entry for the actionable message.

Not all error responses include every field. See the exceptions for 429 and 500 below.

Common error scenarios

400 - Bad request

Returned when the request is invalid or violates a business rule. Duplicate wallet label:

{
  "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 sandbox or production. See the quickstart for how to obtain and configure your credentials.

403 - Forbidden

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

{
  "success": false,
  "message": "access is forbidden",
  "meta": {},
  "errors": [],
  "data": {}
}

404 - Not found

Returned when the requested resource does not exist. Wallet not found:

{
  "success": false,
  "message": "wallet not found",
  "meta": {},
  "errors": [],
  "data": {}
}

Transaction not found:

{
  "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.

{
  "success": false,
  "message": "wallet does not have a bank",
  "meta": {},
  "errors": [],
  "data": {}
}

This commonly occurs when enabling auto-settlement on a wallet that doesn’t have a linked bank account.

429 - Too many requests

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

The 429 response body does not follow the standard error shape. It only returns a message field:

{
  "message": "Too many requests. Please try again later."
}

Your error handling should account for this exception.

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:

{
  "success": false,
  "message": "something went wrong!",
  "meta": {},
  "errors": []
}

For 500 errors, implement retry logic with exponential backoff.

Withdrawal errors

Errors you are most likely to meet on POST /payments/withdraw/address and POST /payments/estimate-network-fee. None of these debit your balance or create a withdrawal.

Request shape

Returned as 422 with the message in errors.

Message	Cause
`{token} does not support a network`	You sent `network` with `BTC`, `LTC`, `DOGE`, or `BCH`. Each runs on one chain, so omit it.
`feeLevel must be one of: low, medium, high`	`feeLevel` was missing or not one of the three values. Required for UTXO withdrawals.
`provide either amount or cryptoAmount, not both`	Send exactly one.
`amount or cryptoAmount is required`	Neither was sent.
`invalid wallet address`	The address is not valid for that token. Check you have not paired an address with the wrong chain.
`token must be one of: BTC, LTC, DOGE, BCH`	The fee estimate endpoint takes UTXO tokens only. Stablecoin fees are flat and come from `GET /payments/supported-assets-info`.

Limits and availability

Returned as 403.

Message	Cause
`the minimum amount required is $5 and the maximum is $100000`	The USD value is outside your integration’s range.
`the minimum crypto amount required is 0.08305648 LTC ($5) and the maximum is 1661.12956811 LTC ($100000)`	Same rule, quoted in coin units when you priced the request with `cryptoAmount`. The bounds move with the market rate.
`{token} withdrawals are currently disabled`	Breet has that token switched off. Temporary; check `GET /payments/supported-assets-info`.
`you can not use a Breet wallet address for this action. Please enter a valid external wallet address`	The destination is a Breet-managed address. Withdrawals must go to an external wallet.

Balance and duplicates

Returned as 400.

Message	Cause
`insufficient balance`	Your USD balance does not cover the amount, plus the fee when your fee bearer is `business`.
`Duplicate withdrawal detected. Enter a different amount.`	You repeated the same USD amount to the same address within 1 minute. See Duplicate withdrawals.
`unable to fetch network fee for {token} on {level} fee level`	The fee could not be quoted. Retry shortly.
`unable to fetch {TOKEN} price`	The market rate was unavailable, so a `cryptoAmount` could not be converted. Retry shortly.

Temporary payout capacity

Returned as 400, on both the withdrawal and the fee estimate endpoints.

{
  "success": false,
  "message": "unable to quote a BTC network fee right now, try a smaller amount or try again later"
}

Breet cannot price a payout of that size in that coin right now. Nothing is debited. Retry with a smaller amount, or try again later — this is a Breet-side limit, not a problem with your request or your balance.

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.

Getting started

Core concepts

Use cases

Response format

Success responses

Error responses

Field-level validation errors

Common error scenarios

400 - Bad request

401 - Unauthorized

403 - Forbidden

404 - Not found

409 - Conflict

422 - Unprocessable entity

429 - Too many requests

500 - Internal server error

Withdrawal errors

Request shape

Limits and availability

Balance and duplicates

Temporary payout capacity

Best practices

​Response format

​Success responses

​Error responses

​Field-level validation errors

​Common error scenarios

​400 - Bad request

​401 - Unauthorized

​403 - Forbidden

​404 - Not found

​409 - Conflict

​422 - Unprocessable entity

​429 - Too many requests

​500 - Internal server error

​Withdrawal errors

​Request shape

​Limits and availability

​Balance and duplicates

​Temporary payout capacity

​Best practices

Response format

Success responses

Error responses

Field-level validation errors

Common error scenarios

400 - Bad request

401 - Unauthorized

403 - Forbidden

404 - Not found

409 - Conflict

422 - Unprocessable entity

429 - Too many requests

500 - Internal server error

Withdrawal errors

Request shape

Limits and availability

Balance and duplicates

Temporary payout capacity

Best practices