Errors

The Error model maps payment provider error codes to player-facing messages. When a transaction fails, Fluid matches the provider’s error code against these records to display the correct title, message, and icon, and to determine what action the cashier should take next.

Fields

Field	Type	Description
Code	string	Internal identifier for the error record (e.g. 3DSECURE-Novatech). Used for back-office reference and search.
Text Title	string	Headline shown to the player when this error is triggered.
Text	text	Body copy shown to the player beneath the title. Supports longer explanations and instructions.
Provider Error Codes	text	Comma-separated list of provider error codes that map to this error record. When a transaction fails, the provider’s error code is matched against these values.
PSP status code	string	Optional PSP status code used to narrow which responses match this error. When set, a record matching both the provider error code and the PSP status code is preferred; if none matches both, a record matching the provider error code alone is used.
Error Action	link	What Try again does for the player. See Error actions.
Icon Selection	string	Icon displayed next to the error message. Each option corresponds to a predefined icon in the cashier UI.
Block subsequent attempts (block_subsequent_transactions)	boolean	In the Faulty Transaction Filter section. When enabled, further attempts with the same payment method and an equal or higher amount are blocked for the Block time below. Enable it for errors that are likely to happen again if nothing changes, e.g. ERR_DECLINED_NO_FUNDS.
Block time (block_time)	integer	How long further attempts are blocked after the first error, in seconds. Leave it empty for no expiry.

Error actions

Error Action	What Try again does
Restart process and clear details	The player restarts the whole process from scratch.
Restart process and preserve details	The player goes back to the first screen; if they keep the same payment method, they don’t have to enter their details again.
Show details step and clear details	The player goes to the details step, with blank fields.
Show details step and preserve details	The player goes to the details step, with the details they just used.

Unmatched codes

A code that no record in the operator’s error set lists shows the copy of that set’s UNKNOWN_ERROR record. See Operator Errors for the resolution order, and remember that a record only applies to an operator once it’s in that operator’s set.

Codes Fluid supplies itself

Most Provider Error Codes come from the payment provider. A few are supplied by Fluid, for outcomes the provider reports without a code of its own. Enter them in Provider Error Codes like any other code. Mapping them is optional, since unmapped codes fall back to UNKNOWN_ERROR, but the generic message is rarely the one you would choose.

Code	What happened	Copy that fits
charge-refused	The gateway would not accept the payment request at all. The card was never shown to the bank.	Something went wrong on our side, not with their card. Ask them to try again shortly or contact support — never suggest a different card.
chargeback-protection	The payment was refused by the gateway’s fraud and chargeback checks, not by the player’s bank.	The payment could not be approved. The card itself is fine, so “declined by your bank” is misleading.

• For charge-refused, telling the player their card was declined sends them to their bank over a problem that is ours. It usually means a configuration is wrong and is being fixed, so leaving Block subsequent attempts off is normally right: blocking further attempts would keep the player locked out after the fix.
• For chargeback-protection, retrying the same card and amount will be refused again, so it’s a good candidate for Block subsequent attempts.

Codes for a refused withdrawal

On brands whose platform approves payouts (see Payment Methods), a refused withdrawal arrives with one of the codes below. Each needs a record listing it under Provider Error Codes, or the player is told only that the withdrawal failed. After creating each record, add it to the operator’s set on the Operator Errors tab, or it is never reached.

These are the player’s most common encounter with a rule they can’t see, so the copy matters more than usual. Say what would let the withdrawal through next time.

Code	What happened	Copy that fits
KYC_REQUIRED	The player has not completed identity verification.	Name the step they need to finish and where to do it. A generic failure message leaves them stuck, because retrying won’t help.
ACCOUNT_RESTRICTED	A restriction on the account blocks payouts.	Point them at support. Don’t imply the amount or method was the problem.
AMOUNT_TOO_LOW	Below the minimum for that method.	Give the minimum. The cashier also shows it, so the message should agree with it.
AMOUNT_TOO_HIGH	Above the maximum for that method.	Give the maximum, and mention that a smaller amount will go through.
DAILY_LIMIT_EXCEEDED	The amount fits the method’s limits, but the player has reached what they may take out that day.	Say the limit resets, otherwise it reads like the account is blocked. Keep it clearly different from AMOUNT_TOO_HIGH.
CARD_METHOD_UNAVAILABLE	A withdrawal to a card was attempted on a brand that doesn’t offer them.	Players shouldn’t reach this. If it appears, a card withdrawal method is active that shouldn’t be, so remove it rather than relying on the copy.
WITHDRAWAL_FAILED	The platform couldn’t process the request, for a reason it didn’t name.	Treat it as temporary. Ask them to try again shortly or contact support.

Note

Enabling Block subsequent attempts on these is rarely right. A withdrawal refused for KYC_REQUIRED or ACCOUNT_RESTRICTED will keep being refused until something changes outside the cashier, and blocking retries only stops the player discovering that the problem is fixed.