# Error Handling

Understand how to identify, interpret, and recover from API errors, payment failures, and transaction processing issues.

Errors and unsuccessful payment outcomes can occur at different stages of payment processing.

Common categories include:

- Authentication and authorization errors
- Request validation errors
- Merchant or gateway configuration errors
- Risk and fraud rule failures
- Processor, network, or issuer declines
- ACH submission errors
- ACH returns
- Settlement or post-processing exceptions
- Internal service errors


Some failures occur before a payment record is created. Others occur after a request has been accepted and may include a payment or transaction identifier.

Use the HTTP status, response fields, returned identifiers, and transaction status together to determine what occurred.

### API and Request Errors

API and request errors occur when the platform cannot process the request as submitted.

Examples include:

- Missing or invalid credentials
- Insufficient permissions
- Missing required fields
- Invalid field values or formats
- Malformed requests
- Unsupported operations
- Merchant configuration problems
- Service or network failures


Depending on where the failure occurs, the response may not include a `paymentId` or other transaction identifier.

### Payment Outcomes

A payment outcome communicates the result of attempting to process a payment.

Examples include:

- Approved
- Partially Approved
- Declined
- Pending
- Returned
- Failed during later processing


An unsuccessful payment outcome is not necessarily an API failure.

The API may successfully receive and process a request while returning a valid decline, pending status, returned transaction, or another unsuccessful financial outcome.

### Understanding the Difference

A successful API request and a successful payment are not always the same thing.

The error-handling flow distinguishes between API request failures and payment outcomes. An API request can either be accepted or result in an API error. When a request is accepted, the payment can have an approved, partially approved, pending, declined, or returned outcome.

**Submit API Request**
Submit the API request for processing.

**Determine Request Result**
The API request is either accepted successfully or results in an API error.

**Handle API Error**
If the API request fails, handle the API error returned by the request.

**Determine Payment Outcome**
If the API request is accepted, evaluate the payment outcome as approved, partially approved, pending, declined, or returned.

API success does not always mean payment success
- An authentication failure may prevent a payment request from being processed.
- A payment request may be processed successfully but later be declined by the processor or issuer.
- A payment request may initially be accepted and later fail during downstream processing.


Always evaluate both the API response and the resulting payment status.

### Card and ACH Outcomes Are Different

Card and ACH payments follow different processing models.

Card payments typically receive an authorization result as part of the initial payment request. ACH payments, however, do not verify available funds or receive issuer authorization in the same way.

An accepted ACH payment may initially have a status of `PENDING` while it moves through ACH processing and settlement. Even after the payment is accepted for processing, it may later be returned by the receiving financial institution.

Do not treat the initial acceptance of an ACH payment as confirmation that funds have been successfully collected. Use subsequent payment status updates to determine the final outcome.

### Error Investigation Guidance

When troubleshooting an issue, review:

- HTTP response status
- Error response details
- Payment identifiers
- Transaction identifiers
- Transaction status
- Processor response information, where available
- Settlement and post-processing events, where applicable


Using these details together provides the most complete understanding of what occurred and what action may be required.

### How to Use This Section

Use the Error Handling documentation to:

- Understand API error responses
- Interpret transaction response codes
- Determine whether a request can be retried
- Recover safely from timeout scenarios
- Prevent duplicate payments
- Troubleshoot payment processing issues


### Related Resources

Error Response Structures
Understand how API error responses are structured, where to find troubleshooting details, and which fields to retain for diagnostics and support.

Response Code Guide
Learn how HTTP status codes, gateway response codes, card-network responses, and ACH return codes relate to payment outcomes.