We use 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, etc.). Codes in the 5xx range indicate an error with our servers.

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.

Response attributes

code string
A short string indicating the error code reported.

message string
A human-readable message providing more details about the error.

errors string[]
A list of reasons that caused the error.

Error codes 🚨

code	description
CODE_ALREADY_EXISTS	A object with a code already exists. Use a different, unique value for `code` and try again
OBJECT_NOT_FOUND	The requested object doesn't exist
INVALID_BODY	The request was unacceptable, often due to missing a required parameter.
INTERNAL_ERROR	Something went wrong on our end
SERVICE_NOT_AVAILABLE	Service not available right now, Please try again later.
BANK_COMMUNICATION_FAILED	Failed to communicate with bank, Please try again later.
BACEN_COMMUNIOCATION_FAILED	Failed to communicate with Brazilian central bank, Please try again later.
PIX_KEY_NOT_FOUND	Pix key not found
RECIPIENT_ACCOUNT_BLOCKED	Recipient's account blocked
RECIPIENT_USER_ACCOUNT_CLOSED	Recipient user account is closed
INSUFFICIENT_BALANCE	Insufficient balance to execute the payment
LIMIT_EXCEED_FOR_THE_TRANSACTION	Payment/withdrawal exceeds the limit allowed.
TRANSACTION_TYPE_NOT_SUPPORTED	The transaction type is not supported/authorized in the recipient user's account
REQUEST_TIMEOUT	The communication with bank resulted in a timeout
TRANSACTION_INTERRUPTED	Transaction interrupted due to error in recipient's bank account
INVALID_RECIPIENT_BANK_ACCOUNT_TYPE	Invalid type for recipient's bank account
DUPLICATE_TRASACTION_DETECTED	An identical transaction is pending. Please wait to retry this operation to avoid duplication.
RECIPIENT_BANK_RESTRICTED	Recipient's bank is currently restricted

Response example

{
  "code": "CODE_ALREADY_EXISTS",
  "message": "The recipient (5a3d6dbb-4ee1-4633-9088-9de8901eef5e) already exists.",
  "errors": []
}