> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction reason codes

> What each Meridian Accounts transaction reason code means and what to do.

`reason` is the machine-readable code to branch on. `statusReason` is an internal reason for your support team. Do not show it to end users or parse it. You receive both on the [Transaction](https://docs.mnai.com/products/meridian-accounts/webhooks/webhooks-transaction.md) webhook and on transactions returned by the API.

> [!WARNING]
>
> Never retry a transaction that failed with `CREDIT_OUTCOME_UNKNOWN`. The money may already have moved, so a retry can pay twice.

| Code | Meaning | What to do |
| :- | :- | :- |
| `CUSTOMER_REQUESTED`, `DUPLICATED_PAYMENT`, `OVERPAYMENT`, `ACCOUNT_DISABLED`, `FAILED_CREDIT`, `OTHER` | Why a refund was requested. A failed refund keeps this value. | Read `status` to see whether the refund failed. |
| `PROVIDER_REJECTED` | The bank or payment provider rejected the transaction. | Do not retry as is. Contact Meridian support. |
| `PROVIDER_REVIEW` | The provider held the transaction for review. On a failed transaction, the provider failed it after that review. | Contact Meridian support. |
| `PROVIDER_RETURNED` | The provider returned a transaction it had reported as complete. | Contact Meridian support for the status of the funds. |
| `RISK_PROVIDER_REJECTED` | Meridian's risk checks declined the transaction. This covers the automated risk assessment, a reviewer's decline, and a deposit into a restricted account. | Do not retry. Contact Meridian support. |
| `RISK_PROVIDER_ERROR` | A system error stopped the risk assessment. | Retry later. |
| `INVALID_DEBIT_PAYMENT_INSTRUMENT` | The debit payment instrument is not valid for this transaction. | Contact Meridian support. |
| `MISSING_DEBIT_PAYMENT_INSTRUMENT` | The transaction has no debit payment instrument. | Contact Meridian support. |
| `INVALID_DEBIT_PAYMENT_INSTRUMENT_RELATED_ENTITY` | The debit payment instrument is the wrong type for this transaction. | Contact Meridian support. |
| `INVALID_DEBIT_OWNER` | The owner of the debit side is not valid for this transaction. | Contact Meridian support. |
| `INACTIVE_DEBIT_PAYMENT_INSTRUMENT_RELATED_ENTITY` | The account being debited is inactive or restricted. | Do not retry. Contact Meridian support. |
| `DEBIT_TRANSACTION_FAILED` | Debiting the funds failed. | Retry later. |
| `DEBIT_TRANSACTION_TIMEOUT` | Debiting the funds timed out. Meridian returns any amount deducted automatically. | Retry later. |
| `INSUFFICIENT_FUNDS` | The amount plus fees exceeds the available balance. | Retry once the balance covers the amount. |
| `DEBIT_LIMIT_EXCEEDED` | The amount exceeds the sending limit. | Retry with a smaller amount, or after the limit resets. |
| `BALANCE_READ_FAILED` | Meridian could not read the balance while checking a withdrawal. | Retry later. |
| `SOURCE_TRANSACTION_NOT_SETTLED` | An auto-sweep did not run because the deposit it moves had not settled. | None. |
| `REVERSAL_FAILED` | The transaction failed and Meridian could not return the deducted amount automatically. A manual return is in progress. | None. Meridian returns the amount manually. |
| `MISSING_CREDIT_PAYMENT_INSTRUMENT` | The transaction has no credit payment instrument. | Contact Meridian support. |
| `INVALID_CREDIT_PAYMENT_INSTRUMENT_RELATED_ENTITY` | The credit payment instrument is the wrong type for this transaction. | Contact Meridian support. |
| `INVALID_CREDIT_OWNER` | The owner of the credit side is not valid for this transaction. | Contact Meridian support. |
| `CREDIT_TRANSACTION_FAILED` | Crediting the funds failed. Meridian returns any amount deducted automatically. | Retry later. |
| `INACTIVE_CREDIT_PAYMENT_INSTRUMENT_RELATED_ENTITY` | The account being credited is inactive or restricted. | Do not retry. Contact Meridian support. |
| `CREDIT_LIMIT_EXCEEDED` | The amount exceeds the receiving limit. | Contact Meridian support. |
| `CREDIT_OUTCOME_UNKNOWN` | The provider accepted the credit but did not confirm the outcome, so the money may have moved. | Do not retry or re-issue: a retry can pay twice. Wait for a final update or contact Meridian support. |
| `UNKNOWN_CREDIT_ERROR` | Crediting the funds failed with an unclassified provider error. | Retry later. |
| `UNSUPPORTED_WITHDRAWAL_DESTINATION` | The withdrawal destination is not supported for this transfer. | Choose another withdrawal account and submit a new withdrawal. |
| `UNLINKED_BANK_ACCOUNT` | The bank account is unlinked. | Link the bank account again, then retry. |
| `RETURNED_NSF` | The external bank returned a direct debit for insufficient funds. | Retry once the external account is funded. |
| `RETURNED_OTHER` | The external bank returned a direct debit for another reason. | Contact Meridian support. |
| `UNSUPPORTED_TRANSACTION_TYPE` | The transaction type is not supported. | Contact Meridian support. |
| `MISSING_PAYMENT_INSTRUMENT` | The transaction is missing a payment instrument. | Contact Meridian support. |
| `MISSING_TRANSACTION_INFO` | Required transaction information is missing. | Contact Meridian support. |
| `USER_INACTIVE` | The user is not active. | Do not retry. Contact Meridian support. |

The API can return other codes. Meridian will add them to this page.
