Payout Failure Reasons

When a PIX payout fails, kamiPay returns a normalized failure reason so you can understand and react to the outcome consistently, regardless of the underlying bank or PSP.

The reason is exposed through three additional fields:

Field	Description
`error_code`	Canonical kamiPay code identifying the failure (stable, safe to branch on).
`error_message`	Human-readable message in English.
`error_category`	One of `bank`, `validation` or `internal`.

These fields are additive. The HTTP status code of the payout endpoint is unchanged, and existing integrations keep working. The raw message from the bank/PSP is never exposed (it is kept internally for support).

Where you receive it

The reason is included both in the synchronous payout response and in the asynchronous failed webhook notification (see Notifications).

On a failed payout webhook, the reason travels inside data:

{
  "status": "failed",
  "transaction_hash": null,
  "data": {
    "error_code": "PAYOUT_AMOUNT_INVALID",
    "error_message": "The payment amount is invalid or does not match the charge.",
    "error_category": "bank"
  },
  "type": "pay",
  "external_id": "your-external-id",
  "kamipay_id": "txc_...",
  "service_type": "prepaid"
}

Bank reasons

The payment reached the receiving institution and was rejected, returned, or could not be settled.

`error_code`	`error_message`	Suggested action
`PAYOUT_AMOUNT_INVALID`	The payment amount is invalid or does not match the charge.	Check the amount against the charge/QR before retrying.
`PAYOUT_INSUFFICIENT_FUNDS`	Insufficient funds to complete the payment.	The payment could not be funded on the paying side.
`PAYOUT_RECEIVER_ACCOUNT_UNAVAILABLE`	The recipient account is blocked, closed, or restricted.	Confirm the destination account with the recipient.
`PAYOUT_RECEIVER_ACCOUNT_INVALID`	The recipient account number or type is invalid.	Verify the recipient account details.
`PAYOUT_RECEIVER_IDENTIFICATION_INVALID`	The recipient's identification (CPF/CNPJ) is invalid or does not match.	Verify the recipient's CPF/CNPJ matches the account holder.
`PAYOUT_REJECTED_BY_RECEIVING_BANK`	The payment was rejected by the receiving bank.	Rejected by the recipient's bank. Contact the recipient.
`PAYOUT_SETTLEMENT_TIMEOUT`	The payment could not be completed by the receiving bank in time.	The transfer could not be settled. You may retry later.
`PAYOUT_TRANSACTION_NOT_SUPPORTED`	This transaction type is not supported by the recipient institution.	The destination does not accept this type of PIX.
`PAYOUT_QR_EXPIRED`	The PIX QR code has expired.	Request a fresh QR code from the recipient.
`PAYOUT_QR_UNAVAILABLE`	The PIX QR code was removed by the recipient and is no longer available.	Request a new QR code from the recipient.
`PAYOUT_QR_ALREADY_PAID`	This PIX QR code has already been paid.	The QR code was already settled; do not retry.
`PAYOUT_QR_INVALID`	The PIX QR code is invalid.	Check the QR/EMV content and try with a valid one.
`PAYOUT_PIX_KEY_NOT_FOUND`	The PIX key was not found.	Verify the PIX key with the recipient.
`PAYOUT_RETURNED`	The PIX payment was returned by the recipient.	The recipient returned the payment.

Validation reasons

The request must be corrected before it can succeed.

`error_code`	`error_message`	Suggested action
`PAYOUT_DESCRIPTION_INVALID`	The payment description contains invalid characters.	Remove unsupported characters from the description and retry.
`PAYOUT_SAME_ACCOUNT`	Cannot transfer to the same account.	The origin and destination cannot be the same account.

Internal reasons

A temporary problem prevented completion. No action is needed on the request itself.

`error_code`	`error_message`	Suggested action
`PAYOUT_TEMPORARY_ERROR`	A temporary error occurred. Please try again later.	Retry the same request after a short delay.

Treat any error_code you don't recognize according to its error_category (for example, an unknown internal code is safe to retry).

Payout Failure Reasons

Where you receive it

Categories

Bank reasons

Validation reasons

Internal reasons

On this page