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": {}
}
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": {}
}
{
"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": {}
}
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."
}
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": []
}
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.
