Payments Direct 2.0 returns standardized error responses for all API requests.
Error responses are designed to be consistent and predictable, making it easier to log, monitor, and resolve issues in your integration.
All error responses include the following fields:
Field | Description |
|---|---|
code | A unique identifier for the error (e.g., USR_067). |
type | Category of the error (e.g., USER_ERROR). |
title | A short human-readable summary of the error. |
description | A concise explanation of the error. Descriptions may be expanded in future updates with more actionable troubleshooting steps. |
status | The associated HTTP status code. |
All Payments Direct errors follow a consistent JSON structure:
{
"code": "USR_067",
"type": "USER_ERROR",
"title": "Insufficient balance",
"description": "Payment failed due to insufficient balance. Add funds before retrying.",
"status": 402
}Errors generally fall into three categories:
Category | Description | Example |
|---|---|---|
| Request-time errors | Occur when an API request is malformed, missing required fields, or includes invalid data. | USR_001 – Invalid request |
| Processing errors | Occur during service execution due to internal or operational constraints. | USR_055 – Service unavailable |
| Payment failures | Occur after a payment has been created but before it completes. These errors often require operational follow-up. | USR_067 – Insufficient balance |
For a complete list of error codes, see the API error codes reference.
- Log and monitor every error response, including code and status.
- Check the error code first, not just the HTTP status, when building your error-handling logic.
- Use the description field for context, but do not rely on it for programmatic decision-making.
- Identify transient vs. permanent errors:
- Retry on transient errors (e.g., network or temporary service issues).
- Do not retry on permanent errors (e.g., invalid data, exceeded limits) until the root cause is corrected.
- Proactively test common error conditions in sandbox environments.
Payment failures are a special class of errors that occur only after a payment is created.
They require you to investigate and resolve the underlying condition before retrying.
Common causes include:
- Insufficient balance
- Credit or transaction limits exceeded
- Past-due invoices
- Invalid or inactive beneficiary account details
For the list of applicable codes, see the Payment failure codes reference section in the error codes reference.
This is the initial release of Payments Direct 2.0 error handling. The schema and error codes are stable for integration, but descriptions will be expanded with more actionable troubleshooting guidance in future updates.