Ticket Failure Codes

When a ticket ends FAILED or PARTIAL-FAILED, its failureCode field says why, as a stable, machine-readable code. Branch your integration on failureCode, not on the text of failureReason.

failureCode sits next to failureReason everywhere a ticket is returned:

• GET /v2/account/tickets/ and GET /v2/account/tickets/{ticket-id}.
• Every TICKET webhook, as data.ticket.failureCode (see Webhook Events).
• The transactions report, as its last column, Failure Code (failureCode in JSON).

It is "" while the ticket has not failed.

failureCode and failureReason

Field	What it is for
failureCode	The reason as a fixed code. Use it in your code: to decide what to show your user, whether to retry, and what to fix.
failureReason	A human-readable explanation for logs and support. Its wording can change, so don't parse it or compare it with fixed strings.
reason	Human-readable progress notes, such as Refund in progress. followed by the refund end-to-end ID. Don't parse it either.

The texts failureReason and reason carry today are unchanged, so an integration that already matches on them keeps working while you move to failureCode.

Stability

• Codes are only ever added. An existing code is never renamed or removed, and its meaning doesn't change.
• New codes can appear without notice. Treat a code you don't recognise as a generic failure: use status to know where the funds are, show a generic message, and log failureReason.

Reading status and failureCode together

status tells you where the money is; failureCode tells you why. Some codes can come with either status, depending on whether the ticket failed while receiving the input or while delivering the output, so always read both.

status	What happened	The funds
FAILED	The ticket failed while receiving the input.	A PIX deposit is returned to the sender. A blockchain or Avenia-balance (INTERNAL) input was not collected.
PARTIAL-FAILED	The input was received, then the delivery failed.	Credited to your Avenia balance, in the currency the operation had reached. Not sent back on-chain.

The exception is INTERNAL_ERROR on a FAILED ticket during delivery: contact support with the ticket id. The full picture of where the funds are after each kind of failure is in Ticket Lifecycle and Failures.

Example

A PIX payout to a beneficiary whose bank is blocked for your account (other ticket fields omitted):

{
  "ticket": {
    "id": "c4bd34dd-cbb2-4cda-b158-f104dd67d0c8",
    "status": "PARTIAL-FAILED",
    "reason": "",
    "failureReason": "ticket failed partially: receiver bank institution is blocked - tokens returned to user's wallet",
    "failureCode": "RECEIVER_BLOCKED_BANK_INSTITUTION"
  }
}

Codes

The Retry? column is a hint for the cases where the answer is clear. A retry always means a new quote and a new ticket.

Pay-in checks

The deposit was refused before it was credited. The ticket ends FAILED and the deposit is returned to the sender.

Code	Meaning	Status	Where the funds are	Retry?
SENDER_BLOCKED_BANK_INSTITUTION	The sender's bank institution is blocked.	FAILED	Returned to the sender.	Not from this institution.
SENDER_BLOCKED_TAX_ID	The sender's tax ID is blocked.	FAILED	Returned to the sender.	Not from this sender.
SENDER_BLOCKED	The sender is blocked.	FAILED	Returned to the sender.	Not from this sender.
THIRD_PARTY_DEPOSIT	Deposits from third parties are not allowed for this user.	FAILED	Returned to the sender.	Pay from the account holder's own bank account.
DEPOSIT_RETURNED	The deposit failed at the payment network and is being returned to the sender.	FAILED	Returned to the sender.

Avenia rules

Limits, compliance and account rules. At pay-in the ticket ends FAILED and the deposit is returned to the sender (an INTERNAL input is not debited). At delivery it ends PARTIAL-FAILED and the amount is credited to your Avenia balance.

Code	Meaning	Status	Where the funds are	Retry?
COMPLIANCE_REJECTED	Rejected for compliance reasons. Permanent for this counterparty.	FAILED or PARTIAL-FAILED	Returned to the sender, or in your balance.	Never, for this counterparty.
COMPLIANCE_TEMPORARY_HOLD	Temporarily held for compliance review.	FAILED or PARTIAL-FAILED	Returned to the sender, or in your balance.	After the hold expires — see below.
COMPLIANCE_UNDER_REVIEW	The counterparty is under compliance review until compliance decides.	FAILED or PARTIAL-FAILED	Returned to the sender, or in your balance.	Not until the review ends.
LIMIT_EXCEEDED	The user's available limit is not enough for this operation.	FAILED or PARTIAL-FAILED	Returned to the sender, or in your balance.	Once the limit allows, or with a smaller amount.
LIMIT_NOT_CONFIGURED	The user has no limit configured for this operation.	FAILED or PARTIAL-FAILED	Returned to the sender, or in your balance.
USER_BLOCKED	The user is blocked.	FAILED or PARTIAL-FAILED	Returned to the sender, or in your balance.	No. Contact compliance@avenia.io.
RECEIVER_BLOCKED_TAX_ID	The receiver's tax ID is blocked.	PARTIAL-FAILED	In your balance.	Not to this receiver.
RECEIVER_BLOCKED_BANK_INSTITUTION	The receiver's bank institution is blocked.	PARTIAL-FAILED	In your balance.	Not to this institution.
RECEIVER_BLOCKED_WALLET_ADDRESS	The receiver's wallet address is blocked.	PARTIAL-FAILED	In your balance.	Not to this address.
RECEIVER_BLOCKED	The receiver is blocked.	PARTIAL-FAILED	In your balance.	Not to this receiver.
THIRD_PARTY_PAYOUT	Payouts to third parties are not allowed for this user.	PARTIAL-FAILED	In your balance.	Only to the account holder.

For COMPLIANCE_TEMPORARY_HOLD, COMPLIANCE_UNDER_REVIEW and COMPLIANCE_REJECTED, the KYT state endpoint and the KYT-STATE webhook tell you the current compliance state and, for a temporary hold, when it expires.

Fee Account

Only for accounts with the Fee Account enabled, on tickets quoted with feeSettlement=FEE_ACCOUNT. Other accounts never receive it.

Code	Meaning	Status	Where the funds are	Retry?
FEE_ACCOUNT_INSUFFICIENT_BALANCE	Your Fee Account does not have enough balance for the ticket's fees.	FAILED or PARTIAL-FAILED	Returned to the sender (an INTERNAL input is not debited), or in your balance.	After topping up the Fee Account.

Receiver's bank

The receiving institution refused or couldn't complete the payout. The ticket ends PARTIAL-FAILED and the amount is credited to your Avenia balance.

Code	Meaning	Status	Where the funds are	Retry?
RECEIVER_BANK_REJECTED	The receiver's bank rejected the payment.	PARTIAL-FAILED	In your balance.	Confirm the account with the beneficiary first.
RECEIVER_BANK_TIMEOUT	The receiver's bank timed out.	PARTIAL-FAILED	In your balance.	Yes, it may succeed later.
RECEIVER_BANK_UNAVAILABLE	The receiver's bank answered with an error or an invalid response.	PARTIAL-FAILED	In your balance.	Yes, it may succeed later.
RECEIVER_BR_CODE_NOT_PAYABLE	The QR code can no longer be paid: it expired, was already paid or was refused by the receiver.	PARTIAL-FAILED	In your balance.	Not with the same QR code.
RECEIVER_BR_CODE_INVALID	The QR code is invalid.	PARTIAL-FAILED	In your balance.	After fixing the QR code.
RECEIVER_PIX_KEY_INVALID	The PIX key is invalid or does not exist.	PARTIAL-FAILED	In your balance.	After fixing the PIX key.
RECEIVER_ACCOUNT_INVALID	The receiver's account details are invalid.	PARTIAL-FAILED	In your balance.	After fixing the account details.
RECEIVER_ACCOUNT_BLOCKED_BY_BANK	The receiver's account is blocked or restricted by its bank.	PARTIAL-FAILED	In your balance.	Not to this account.
RECEIVER_ACCOUNT_CLOSED	The receiver's account is closed.	PARTIAL-FAILED	In your balance.	Not to this account.
RECEIVER_ACCOUNT_LIMIT_EXCEEDED	The amount is above what the receiver's account accepts.	PARTIAL-FAILED	In your balance.	With a smaller amount.

Blockchain or Avenia-balance input

The input couldn't be collected. The ticket ends FAILED and nothing was debited.

Code	Meaning	Status	Where the funds are	Retry?
INSUFFICIENT_BALANCE	The sending wallet or balance does not have enough funds.	FAILED	Not collected.	After topping up.
INSUFFICIENT_ALLOWANCE	The sending wallet did not approve enough allowance.	FAILED	Not collected.	After raising the allowance.
INVALID_SIGNATURE	The permit or signature is invalid.	FAILED	Not collected.	After signing again.
WALLET_NOT_AUTHORIZED	The sending wallet is not authorized for this operation.	FAILED	Not collected.
SLIPPAGE_EXCEEDED	The price moved beyond the accepted slippage.	FAILED	Not collected.	Yes.
TRANSACTION_DEADLINE_EXPIRED	The transaction deadline expired before it executed.	FAILED	Not collected.	Yes.

Payout, refund and general

Code	Meaning	Status	Where the funds are	Retry?
PAYOUT_FAILED	The payout failed at the payment network.	PARTIAL-FAILED	In your balance.
PAYOUT_RETURNED	The payout was sent and then returned.	PARTIAL-FAILED	In your balance.
PAYOUT_UNAVAILABLE	This payout route is temporarily unavailable.	PARTIAL-FAILED	In your balance.	Yes, later.
UNSUPPORTED_ROUTE	This payout route is not supported for this ticket.	PARTIAL-FAILED	In your balance.	Not on this route. See Available Combinations.
REFUND_WINDOW_EXPIRED	The original payment can no longer be refunded.	PARTIAL-FAILED	In your balance.	No.
ALREADY_REFUNDED	The original payment was already refunded.	PARTIAL-FAILED	In your balance.	No.
REFUND_AMOUNT_EXCEEDS_ORIGINAL	The refund amount exceeds the original payment.	PARTIAL-FAILED	In your balance.
REFUND_FAILED	The refund failed.	PARTIAL-FAILED	In your balance.
INTERNAL_ERROR	An internal error on Avenia's side.	Any — read status	Depends on status. On a FAILED ticket during delivery the input may already have been debited.	It may succeed later. If funds look stuck, contact support with the ticket id.