ReceiverBank Errors
This section documents errors returned by the receiving bank or payment provider during a PIX transaction.
These errors do not come from your request format or authentication.
They are responses from external banking systems that prevent the transaction from being completed.
When one of these errors happens:
The transaction is automatically marked as failed
No funds are transferred to the receiver
How to Use These Errors
Use this list to:
Understand why a payment failed at the banking level
Decide whether the transaction can be retried
Show clear and accurate messages to your end user
Build fallback or recovery flows
Some errors are temporary (for example, bank instability), while others are permanent (for example, invalid PIX key or blocked account).
You should always rely on the error code to decide:
If you can retry automatically
If you should ask the user to change data
If the operation must be canceled permanently
These errors are critical for building a reliable and user-friendly payment experience.
PMT_ERR_401
Mismatch between the account holder and the provided data.
PMT_ERR_402
PIX key query attempt limit reached.
PMT_ERR_403
One or more required fields are missing or contain invalid data.
PMT_ERR_404
The provided PIX key is invalid.
PMT_ERR_405
The PIX key is temporarily blocked.
PMT_ERR_406
Insufficient balance to complete the transaction.
PMT_ERR_407
The receiving account is blocked.
PMT_ERR_408
The receiving bank is blocked for transactions.
PMT_ERR_409
The receiving account has been closed.
PMT_ERR_410
The receiving bank blocked the transaction.
PMT_ERR_500
It's not possible to process the payment due a integration error.
PMT_ERR_504
Bank provider returned unexpected error!
PMT_ERR_413
The receiving bank failed this transaction
PMT_ERR_414
Refund not allowed.
PMT_ERR_415
Refund exceeds original amount.
PMT_ERR_416
The sender account is blocked!
PMT_ERR_417
Recipient account does not allow this type of transaction.