Error codes | Direct Debit

When a charge is declined, the response includes a declined_reason (platform-level code) and a declined_reason_rail (banking network code). Both are also present in SFTP response files.

Platform error codes

declined_reason normalizes the bank’s response into a platform code. A few codes, such as risk_engine, are set by Monato before the charge is sent to the bank.

Code	Description	Recommended Action
`insufficient_funds`	The customer’s account does not have enough funds to cover the charge.	Retry at a later date or contact the customer.
`account_blocked`	The account is blocked for direct debit charges. See the bank error code for the specific reason.	Check the `declined_reason_rail` code for detail. Do not retry without resolving the underlying account issue.
`risk_engine`	The charge was rejected by the Monato risk engine.	Review the charge details. Contact Monato support if the rejection appears incorrect.
`undetermined`	The platform could not determine a specific decline reason. See the bank error code for detail.	Check the `declined_reason_rail` code for the bank’s response.

Codes mapped from the bank response

Each of these codes comes from one bank response code, which you also get in declined_reason_rail.

Code	Bank code	Description
`account_does_not_exist`	01	The account does not exist.
`account_canceled`	03	The account is canceled.
`account_in_other_currency`	05	The account is in a different currency.
`account_not_belongs_to_bank`	06	The account does not belong to the receiving bank.
`transaction_duplicated`	07	Duplicate transaction.
`client_order_declined_pay_to_issuer`	08	The customer told the bank not to pay this issuer.
`client_order_amount_is_more_than_authorized`	09	The amount is higher than the customer authorized.
`client_order_canceled`	10	The customer canceled the service.
`client_service_not_authorized`	11	The customer has not authorized the service.
`payment_order_expired`	12	The payment order expired.
`client_rejected_charge`	13	The customer does not recognize the charge. The charge becomes `chargeback`, not `declined`.

insufficient_funds is bank code 04 and account_blocked is bank code 02. Any other bank code declines the charge with undetermined; check declined_reason_rail for the bank’s code. Penny validation can also set account_canceled or account_does_not_exist when it cancels a charge.

Bank error codes

These codes are returned by the Mexican banking network (SPEI / Domiciliación Bancaria) and appear in the declined_reason_rail field.

Code	Description
01	Cuenta inexistente — Account does not exist
02	Cuenta bloqueada — Account is blocked
03	Cuenta cancelada — Account is cancelled
04	Cuenta con insuficiencia de fondos — Insufficient funds
05	Cuenta en otra divisa — Account is in a different currency
06 / 6	Cuenta no pertenece al banco receptor — Account does not belong to the receiving bank
07 / 7	Transacción duplicada — Duplicate transaction
08	Por orden del cliente: Orden de no pagar a ese Emisor — Customer instructed bank not to pay this issuer
08	Baja por oficina — Deregistered by branch
09	Por orden del cliente: Importe mayor al autorizado — Amount exceeds the amount authorised by the customer
10	Por orden del cliente: Cancelación del servicio — Customer cancelled the service
10	Domiciliación dada de baja — Direct debit mandate deregistered
11	Cliente no tiene autorizado el servicio — Customer has not authorised the service
11	Domiciliación dada de baja — Direct debit mandate deregistered
12	Vencimiento de la Orden de Pago en Ventanilla — Payment order expired
13	Cliente desconoce el cargo — Customer does not recognise the charge
19	Tipo de cuenta no admite domiciliaciones — Account type does not support direct debit
20	Indomiciliado — Not enrolled for direct debit
22	Domiciliación ya existe — Direct debit already exists (affiliation response)
23	Baja por oficina — Deregistered by branch
24	No se procesó CARGO/ABONO a empresa — Charge/credit to company was not processed
25	Todas las domiciliaciones de la cuenta fueron dadas de baja — All direct debits on the account were deregistered
26	Domiciliación dada de baja — Direct debit mandate deregistered
27	El importe actual supera al importe original o viceversa — Current amount exceeds or is less than the original amount
28	Banco no válido o no participante — Invalid or non-participating bank
29	Banco no válido o no participante — Invalid or non-participating bank
30	Domiciliación no realizada — Direct debit not executed
31	Entidad no válida — Invalid entity
32	Error no específico de red interbancaria — Non-specific interbank network error
33	Monto cobrado excede límite configurado — Charged amount exceeds configured limit
36	Domiciliación no realizada por error general — Direct debit not executed due to general error
46	Cuenta del receptor inválida — Invalid recipient account
88	Cuenta bloqueada — Account is blocked
91	Error no específico de red interbancaria — Non-specific interbank network error

API request errors

These errors are returned synchronously by the API, before a charge is created.

Status	When	Source
`400 Bad Request`	The `Idempotency-Key` is not a valid UUID	`POST /charges`
`400 Bad Request`	The charge references an instrument that is not `active`, for example one that failed penny validation (`instrument_in_invalid_state`)	Penny validation
`401 Unauthorized`	The `x-api-key` header is missing or invalid, or the key was revoked	Quickstart
`409 Conflict`	A request with the same `Idempotency-Key` is still being processed. Retry shortly.	Create charges
`422 Unprocessable Entity`	The request failed validation, or an `Idempotency-Key` was reused with a different body	API reference

Validation errors (422) use the HTTPValidationError shape from the OpenAPI spec. The values below are placeholders:

{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "<error message>",
      "type": "<error type>"
    }
  ]
}

{
  "error_code": "invalid_input",
  "error_message": "instrument_in_invalid_state"
}