ACH Error Reference & Troubleshooting

This page provides reference information for understanding ACH error responses, status codes, and troubleshooting common issues. For transaction-specific errors, see the individual documentation pages:

ACH Verify - Bank account verification errors
ACH Sale Transactions - Payment processing errors
ACH Refunds - Refund-specific errors

Error Response Format

All Preczn API errors follow this format:

{
  "message": "Human-readable error message",
  "error": "Error Type",
  "statusCode": 400
}

Single Validation Error

{
  "message": "Routing number must be exactly 9 digits",
  "error": "Bad Request",
  "statusCode": 400
}

Multiple Validation Errors

When multiple fields fail validation, message contains an array:

{
  "message": [
    "Routing number must be exactly 9 digits",
    "Account number must be between 4 and 17 digits"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

Not Found Error

{
  "message": "Transaction Id Not Found",
  "error": "Not Found",
  "statusCode": 404
}

HTTP Status Codes

Status Code	Error	Description
`400`	Bad Request	Validation errors, invalid field values
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Invalid merchant ID or transaction ID
`422`	Unprocessable Entity	Valid format but business rule violation
`500`	Internal Server Error	Internal processing error

Transaction Status Codes

ACH transactions use single-character status codes in the authorization.status field:

Code	Status	Description
`P`	Pending	Transaction submitted, awaiting ACH network processing
`A`	Approved	Transaction successfully completed
`D`	Declined	Transaction was declined by processor or bank
`E`	Error	An error occurred during processing

Unsupported Transaction Types

ACH only supports sale, refund, and verify transaction types. Attempting other types returns these errors:

Error	Message	Cause	Solution
Bad Request	`Authorization is not supported for ACH transactions. Use 'sale' transaction type instead.`	Attempted `auth` transaction	Use `type: "sale"` instead
Bad Request	`Capture is not supported for ACH transactions. Use 'sale' transaction type instead.`	Attempted `capture` transaction	Use `type: "sale"` instead
Bad Request	`Void is not supported for ACH transactions. ACH transactions can only be refunded after settlement (typically 3 business days).`	Attempted `void` transaction	Wait for settlement, then use `type: "refund"`
Bad Request	`Drawdown is not supported for ACH transactions. Drawdown is only applicable for lending payment methods.`	Attempted `drawdown` transaction	Drawdown is not available for ACH

ACH-Supported Processors

ACH transactions require a processor that supports ACH. The following processors are ACH-enabled:

Payrix
Adyen
Adyen for Platforms
Finix
Authorize.Net
AffiniPay
Braintree

If your merchant's plan doesn't include an ACH-enabled processor, you'll receive: ACH transaction not supported for this Plan

Troubleshooting Guide

Transaction Stuck in Pending

Symptoms: Transaction remains in "Pending" status for more than 3 business days.

Possible Causes:

ACH network delays
Bank processing delays
Weekend or holiday submission

Solutions:

Check for webhook notifications
Contact support if pending > 5 business days
Verify the transaction with GET /v1/transactions/{id}

Repeated Declines

Symptoms: Multiple transactions for the same account are declined.

Possible Causes:

Incorrect account details
Insufficient funds
Account closed
Bank restrictions

Solutions:

Verify routing and account numbers with customer
Request customer contact their bank
Try alternative payment method

Refund Fails

Symptoms: Refund request returns an error.

Checklist:

Is the original transaction settled? (Wait 1-3 business days)
Does the refund amount exceed the original?
Have you already refunded the full amount?
Is the transaction ID correct?

Webhook Not Received

Symptoms: Transaction status changed but no webhook was received.

Solutions:

Verify webhook URL is correct and accessible
Check webhook subscription includes transaction events
Review webhook logs in dashboard
Test webhook endpoint with a simple POST request

Getting Help

If you continue to experience issues:

Review the transaction-specific documentation for detailed error tables
Review webhook logs in your dashboard
Contact support with:
- Transaction ID
- Error message received
- Request payload (with sensitive data removed)
- Timestamp of the issue