# Error Codes & Messaging

Diagnose and resolve payment processing issues.

Error messages identify issues that prevent payment files, payment records, or API requests from being processed successfully.

Payment Network returns errors during validation, routing, fulfillment, and other processing activities. Understanding these errors can help you diagnose issues, correct invalid data, and resubmit requests when necessary.

Most errors fall into three categories:

- Request validation errors
- Payment validation errors
- Processing errors


### Common Errors

#### Payment Validation

| Error Message | Cause | Resolution |
|  --- | --- | --- |
| `routing_number must be exactly 9 characters long` | Routing number is invalid. | Use a 9-digit routing number. |
| `account_number must be numbers or spaces only` | Account number contains unsupported characters. | Use numeric characters and spaces only. |
| `amount is invalid` | Payment amount is missing or incorrectly formatted. | Use a numeric value with exactly two decimal places. |
| `check_number must be 1 to 15 digits long` | Check number is outside the supported length. | Use a value between 1 and 15 characters. |
| `address_line_1 should not be empty` | Required address information is missing. | Provide a valid recipient address. |


#### Attachment Errors

| Error Message | Cause | Resolution |
|  --- | --- | --- |
| `attachment url should not be empty` | Required attachment was not provided. | Provide a valid attachment URL. |
| `attachment url is not allowed` | Attachment location isn't approved. | Use an approved and accessible location. |
| `attachment is unavailable` | Attachment could not be retrieved. | Verify the URL and file availability. |
| `attachment file type is not supported` | Unsupported document type. | Use a supported document format. |
| `attachment file type is not recognized` | File extension and content do not match. | Verify that the document contains valid file content. |


#### Signature Errors

| Error Message | Cause | Resolution |
|  --- | --- | --- |
| `signature url is empty` | Required signature URL was not provided. | Provide a valid signature URL. |
| `signature has wrong url format` | Signature URL is malformed. | Use a valid URL format. |
| `signature is not accessible via url` | Signature image cannot be retrieved. | Verify accessibility and permissions. |
| `signature file type is not supported` | Signature image format is unsupported. | Convert the image to a supported format. |
| `signature file size has exceeded the valid maximum` | Signature image exceeds the size limit. | Reduce the file size before submission. |


#### File-Level Errors

| Error Message | Cause | Resolution |
|  --- | --- | --- |
| `File is unreadable` | File format is invalid or corrupted. | Verify that the file is a valid CSV. |
| `File is empty` | File contains no payment records. | Add at least one payment record. |
| `File contains only headers` | File contains headers but no data. | Add one or more payment records. |


#### Routing & Matching Errors

| Error Message | Cause | Resolution |
|  --- | --- | --- |
| `No suitable route could be identified` | Payment could not be matched to a valid destination. | Verify lockbox, routing, and payee information. |


### Prevent Common Errors

To reduce validation and processing failures:

- Validate payment files before submission.
- Ensure required fields are populated.
- Verify routing and account information.
- Confirm attachment and signature URLs remain accessible.
- Test with representative payment data before moving to production.
- Monitor recurring validation failures and correct the source data.