Skip to main content

Handling Batch Errors

Common validation errors, partial failures, and how to fix and retry.

Written by Ryan O
Updated today

Overview

Batch payouts can encounter errors at two stages: during initial file validation and during payout processing. Understanding these errors helps you resolve issues quickly and ensure your payments go through.

Validation Errors

Validation errors occur when Anton parses your uploaded file. These are reported per row before you confirm the batch. Common validation errors include:

  • Payee not found -- The payee_id does not exist in your account. Verify the payee was created and the ID is correct.

  • Instrument not found -- The instrument_id does not exist or does not belong to the specified payee.

  • Invalid amount -- The amount is zero, negative, or not a valid number. Amounts must be positive decimals (e.g., 500.00).

  • Unsupported currency -- The currency code is not recognized. Use three-letter ISO 4217 codes in uppercase.

  • Missing required field -- A required column (payee_id, instrument_id, amount, or currency) is empty.

Retrieving Error Details

After uploading, check for errors using the errors endpoint:

curl https://api.antonpayments.dev/v1/batches/batch_abc123/errors \
  -H "Authorization: Bearer ak_test_..."

The response lists each error with the row number, field name, and a descriptive message. In the merchant portal, errors are highlighted inline in the batch review screen.

Fixing Validation Errors

You have two options when a batch contains validation errors:

  • Fix and re-upload. Correct the errors in your CSV file and upload it as a new batch. The original batch can be cancelled.

  • Confirm with valid rows only. If only a few rows have errors, you can confirm the batch as-is. Error rows are automatically skipped and only valid rows are processed as payouts.

Processing Failures

After a batch is confirmed, individual payouts may still fail during processing. These are separate from validation errors and can occur due to:

  • Compliance screening rejection -- The payout was flagged and blocked by sanctions or compliance checks.

  • Insufficient balance -- Your available balance dropped below the required amount between confirmation and processing.

  • Rail errors -- The payment rail returned an error (e.g., invalid account details at the bank level, network timeout).

  • Instrument issues -- The bank account or payment method was closed or invalid at the destination.

Handling Partial Failures

Batches can partially succeed. The batch status becomes completed as long as at least some payouts succeeded, even if others failed. To identify failures:

curl "https://api.antonpayments.dev/v1/batches/batch_abc123/payouts?status=failed&limit=50" \
  -H "Authorization: Bearer ak_test_..."

Each failed payout includes error details explaining the reason for failure.

Retrying Failed Payouts

There is no automatic retry for failed payouts within a batch. To retry:

  1. Identify the failed payouts using the filtered payouts endpoint above.

  2. Resolve the underlying issue (e.g., update instrument details, add funds, or address compliance flags).

  3. Create new individual payouts for the affected recipients, or prepare a new batch file with only the failed rows.

Tips for Reducing Errors

  • Validate payee and instrument IDs exist before including them in your batch file.

  • Test with a small batch in sandbox before running large production batches.

  • Ensure your available balance covers the full batch amount before confirming.

  • Subscribe to webhook events (batch.completed, payout.failed) for real-time error notifications.

Did this answer your question?