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	Additional error details when available.
`meta`	object	Empty for error responses.
`data`	object	Empty for error responses.

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 development 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.

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

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

Best practices

​Response format

​Success responses

​Error responses

​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

​Best practices

Response format

Success responses

Error responses

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

Best practices