Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

Errors and Decline Codes

Card acquiring errors follow the error format of the rest of the API: an HTTP status and a JSON body with an error field, sometimes with an extraInfo that says more.

JSON
{ "error": "InvalidFieldError: device.ipAddress is invalid" }

Field names in error messages are the names of the request, in camelCase (payerEmail, saveCard.customerReference). Match on the HTTP status and the message prefix (InvalidFieldError, NotFoundError and so on): the wording after the prefix can be improved without notice. For a payment that ended BLOCKED, DECLINED or ERROR, or a refund or a settlement that ended FAILED, match on failureCode, which is stable.

Decline buckets​

A declined payment event and a read of the payment carry declineBucket, so you know what to tell your customer. The synchronous answer of POST /payments carries failureCode but not declineBucket: take it from the webhook or from GET /payments/{payment-id}. The customer never sees the reason on the hosted page, by design.

declineBucketMeaningWhat to do
RETRYABLEThe refusal may pass if the customer tries the same card later: insufficient funds, "do not honor", or a new card the bank has not unlocked yet (first use).Offer a new attempt (a new quote) after the customer had the chance to fix the cause, such as adding funds or unlocking the card in the bank's app.
TERMINALThe same card will not pass.Ask for another card.

RETRYABLE means "may pass if tried later", not "retry now": do not repeat the charge in a loop. Every attempt is a card tried, and a caller that repeats at once only collects more declines. Avenia never retries a declined payment on its own, and you should not retry without the customer either.

On the hosted page a decline is per attempt: the customer may try another card on the same payment, which can still be captured. Offer a new attempt with a new quote only after the session has ended without a capture: see Trying another card.

A card reported lost, stolen or to be picked up is always TERMINAL and ends DECLINED with failureCode FRAUD_DECLINED. A decline Avenia cannot place is TERMINAL: asking for another card is the safe answer. declineBucket is "" on every event that is not a decline.

Sub-statuses and failure codes​

subStatus refines a terminal status:

statussubStatusMeaning
DECLINEDISSUER_DECLINEDThe customer's bank refused.
DECLINEDFRAUD_DECLINEDRefused by fraud screening, or by an issuer that reports the card lost, stolen or to be picked up.
ERRORINTERNAL_ERROREvery ERROR: the authorization did not complete, on our side or at the acquirer.
EXPIREDCHECKOUT_ABANDONEDThe customer left without paying.
EXPIREDCAPTURE_WINDOW_LAPSEDOur failure to capture in time; the customer was not charged. Tell Avenia.

failureCode names the reason a payment ended BLOCKED, DECLINED or ERROR. It is on the answers that return the payment (POST /payments, the saved-card charge, GET /payments/{payment-id}) and on the payment events, and is "" for any other status. Codes are only ever added, never renamed or removed: treat an unknown one like the status it came with.

statusfailureCodeMeaning
BLOCKEDUSER_BLOCKEDYour account (or the sub-account) is blocked, or card acquiring was turned off for it after the sale was opened. Refused before the issuer was called. Contact Avenia if unexpected.
DECLINEDISSUER_DECLINEDThe customer's bank refused. declineBucket says whether the same card may work later.
DECLINEDFRAUD_DECLINEDRefused by fraud screening, or because the issuer reports the card lost, stolen or to be picked up; always TERMINAL.
DECLINEDDECLINEDDeclined with no finer reading.
ERRORINTERNAL_ERRORThe authorization did not complete, on our side or at the acquirer; the code does not say which. No money moved. Offer a new attempt, and contact Avenia if it repeats.

Refund failure codes​

A refund's failureCode names why it ended FAILED, when the cause is one you can act on. It is on each refund in refunds when you read the payment, and on the refund events. It is "" on any other refund, including one a person rejected, one whose approval expired and one the acquirer refused. Codes are only ever added, never renamed or removed.

failureCodeMeaning
PAYMENT_NOT_REVERSIBLEThe refund waited for approval while its payment stopped being reversible (a chargeback landed): sending it would have paid the cardholder twice. Nothing was sent.

Settlement failure codes​

A settlement's failureCode names why it ended FAILED. It is on GET /settlements/{settlement-id} and in the settlement events, and is settlementFailureCode, beside settlementStatus, on statement lines and early settlement reads. It is "" on every status but FAILED. A settlement that fails sends no event: you learn of it by reading the settlement. Codes are only ever added, never renamed or removed: treat an unknown one like INTERNAL_ERROR.

failureCodeMeaningWhen
INTERNAL_ERRORThe payout did not land, for a cause on Avenia's side. Nothing was paid; there is nothing for you to change. Contact Avenia.A settlement ends FAILED: the transfer to the payout wallet was refused before anything was sent, or was found not to have landed.

HTTP errors​

HTTPerror (examples)What to do
400card data must be encrypted before it reaches this APIA readable card number reached the API: the request bypassed the relay, or the card is outside card.encrypted. Send it to the relay URL: see Server-to-Server Payments.
400InvalidBodyError: could not parse body dataInvalid JSON, a string where a number goes (expirationMonth), an amount or rate that is not a number ("ten", ""), or a body over 4 KB. With "extraInfo": "content after the JSON object": send one JSON object and nothing after it.
400InvalidFieldError: card.encrypted.<field> is invalid, with "extraInfo": "card fields must arrive encrypted by the relay"The card field arrived unencrypted or damaged. Check that the request went through the relay and that the field sits under card.encrypted.
400InvalidFieldError: device.<field> is invalidFix that field of the device block.
400InvalidFieldError: <field> is invalidFix the named field. extraInfo can say why: a decimal that is not plain (exponent notation, more than 20 digits before the point or 18 after), an amount with more than 2 decimal places, above your limit or below the minimum, or an externalId longer than 68 characters.
400InvalidFieldError: successUrl is invalid (or cancelUrl)The URL is not https, or not on your registered domains. Nothing was charged.
400InvalidFieldError: <field> is invalid, with "extraInfo": "not a field of this request"The body has a field the request does not take. Remove it.
400InvalidFieldError: <key> is invalid on a GET, or on any route with a query key it does not takeA query parameter the route does not take. Only the parameters listed for each route, and subAccountId, are accepted.
400InvalidFieldError: subAccountId is invalidsubAccountId is not a UUID.
400InvalidFieldError: saveCard.customerReference is invalid or saveCard.cardholderConsented is invalidSee Saved Cards.
400InvalidFieldError: savedCard.savedCardId is invalid, savedCard.customerReference is invalid, card is invalid or saveCard is invalidSee Saved Cards.
400InvalidFieldError: beneficiaryWalletId is invalidNot one of your beneficiary wallets (not a UUID, unknown, or another account's). Name one of the selling account's wallets: see settling a sale to a wallet.
400InvalidFieldError: beneficiaryWalletId is invalidThe wallet's chain is not the chain of the quote's output. Name a wallet on that chain, or quote the sale again for the wallet's chain.
400InvalidFieldError: beneficiaryWalletId is invalidNo beneficiaryWalletId, and the quote's output is on a blockchain. Name a wallet on that chain, or use a quote whose output is INTERNAL to be paid to your account's balance.
400InvalidFieldError: beneficiaryWalletId is invalid, with "extraInfo": "the destination sub-account is hidden"The wallet is the wallet of another account of your workspace that is hidden from your dashboard. Name another wallet.
400InvalidFieldError: beneficiaryWalletId is invalidA beneficiaryWalletId with a quote whose output is INTERNAL. Leave it out: the sale is paid to your account's balance.
400InvalidFieldError: quoteToken is invalidThe quoteToken is missing, unreadable, expired, another account's or not a card sale quote, the card price changed since the quote, its markup is above your workspace's cap, or its amount is too small to settle. extraInfo says which: see the quote token. Quote the sale again.
400InvalidFieldError: amount is invalid, with "extraInfo": "not a field of this request"A sale has no amount: its amount is the quote's inputAmount. Remove the field.
400InvalidFieldError: installments is invalidMore installments than your maximum, or installments on a debit card.
400only BRL is accepted as the sale currencySend currency as BRL.
400the X-API-IdempotencyKey header is required on this routeAdd the header (refunds and dispute evidence).
400an early settlement needs an idempotency keyAdd the X-API-IdempotencyKey header to the early settlement.
400prepaid cards are not acceptedAsk for another card.
400confirmAmount is not this dispute's amount: nothing was acceptedSend the dispute's amount.
401UnauthorizedErrorCheck key id, timestamp (milliseconds, clock in sync), signature and IP: see Authentication. On the payment route, also: the payments key's allowlist holds the relay's addresses, the signed body is the canonical body without card.encrypted, and no key is repeated ignoring case.
402the payment was refusedRefused by Avenia, for example by its risk rules. Offer another card, with a new quote. A payment that failed on our side or at the acquirer answers 500, not 402.
403ForbiddenErrorRefunds, dispute decisions and early settlements need an admin access, or the sub-account is blocked for this access.
404NotFoundError: subAccountId not foundThe sub-account is not one of yours.
404NotFoundError: account not foundThe account (or the sub-account named in subAccountId) has no card acquiring configuration. Contact Avenia.
404NotFoundError: payment not found, settlement not found, dispute not found, saved card not foundWrong id, or it belongs to another account or sub-account.
404settling on demand exists only in the sandbox; here settlements run on their own schedule, simulating a refund decision exists only in the sandbox; here a person decidesThese routes exist only in the sandbox.
409an authorization for this quoteToken is already runningWait a few seconds and repeat.
409this quoteToken has already been paidQuote again for a new payment.
409this quoteToken already opened a sale with different terms; send the same request to retry it, or quote the sale again for a new oneA quote token opens one sale, on one entry point. Repeat the same request, or quote again. This is also the answer when you correct a request that was refused with a 400 after its session was created (installments, a prepaid card, an amount above a limit): quote again and send the corrected request with the new quoteToken.
409QUOTE_EXPIRED: the quote of this sale has expired; quote the sale againThe payment started after its quote's 5 minutes; nothing was charged. Match the QUOTE_EXPIRED: prefix. Quote again and send the new quoteToken. On the hosted page the customer gets 409 {"code": "QUOTE_EXPIRED", "message": "this price has expired -- please return to the store and start the purchase again"}.
409this checkout session was cancelledThe session was cancelled while its payment was being authorized; nothing was charged.
409an authentication for this quoteToken is already in progress, on payment <id>, and it cannot be restarted from hereA 3D Secure challenge is open for this sale. Reconcile with that payment.
409the account is blocked and cannot accept paymentsYour account (or the sub-account) is blocked for acquiring. Contact Avenia.
409the account is not ready to accept payments yetThe account's acquiring set-up is not complete. Contact Avenia.
409the reversal is larger than what is left of this payment, this payment cannot be reversed in its current stateSee Refunds.
409Refund approval: the request to approve this refund expired; the refund was closed refused and nothing was sent, the payment no longer has this much left to refund; nothing was approved, the payment can no longer be refunded; the waiting refund was closed and nothing was sentNothing was sent to the customer.
409Saved-card and dispute errorsSee Saved Cards and Card Disputes.
409Early settlement errorsSee Early settlements.
429checkout session creation limit reached for this account; retry laterSlow down: see the limits below.
429this payment was read from the provider a moment ago; retry shortly to get the address for the authentication in progress on payment <id>Repeat after a few seconds.
500InternalError: please contact usSomething failed on our side or at the acquirer; the answer never says which. Repeat once with the same quoteToken and body (payments) or X-API-IdempotencyKey (refunds, early settlements); if it persists, send Avenia the time and the reference. A refund: see When a refund does not go through. A contest: see Card Disputes errors.

Retry policy. It is safe to repeat any 5xx or a timeout with the same quoteToken and body (payments) or the same X-API-IdempotencyKey (refunds, evidence, early settlements): you get the existing result back, never a second charge or refund. Do not repeat a 4xx without fixing the request.

Limits​

LimitSandbox value
Amount per paymentR$ 5,000.00 ("5000.00"). Above it, the payment is refused with 400 InvalidFieldError: amount is invalid. Your account also has a monthly volume limit.
Payments per seller60 per hour and 500 per day (UTC day). Above it: 429.
Payments per quoteToken1
Charges of saved cardsR$ 5,000.00 per charge, 60 per hour, 500 per day.
InstallmentsUp to 12, credit cards only. In production your contract decides.
Request body4 KB (a dispute evidence upload: about 1.1 MB).
Schedule and statement readsAt most 366 days per read, 500 entries per page (100 by default).
Webhook URLs per account3
Request timestamp tolerance60 seconds, either way.
Checkout session life5 minutes: the life of its quote.