Handling Errors in Attachment Submissions transactions

The Attachments Submission API provides useful error information when the request body contains mistakes or when something else in the process goes wrong. Except where noted, all errors described in this section apply to both Unsolicited and Solicited transactions.

The vast majority of error messages contain the following fields:

  • field (error.field)
  • description (error.description)

Generic Unable to Process errors

When using the API, you might encounter an occasional Unable to process the request at this time, please try again later error message. This is the equivalent of an HTTP 500 error. It typically occurs with temporary network connection problems such as a disconnected VPN (if using a VPN), physical connection interruptions, client operating system errors requiring a reboot, or temporary API service interruptions. To address these issues, check your network infrastructure, ensure your API console is operating correctly, or simply wait a few minutes and try again.

Specifying the wrong payer

If you accidentally specify the wrong payer, or a payer that doesn't support digital attachment capabilities, you'll see the following error:

{
    "status": "errors",
    "errors": [
        {
            "field": "tradingPartnerServiceId",
            "description": "trading partner not established for digital attachments, please provide a payerFaxNumber or payerAddress"
        }
    ]
}

When you forget to attach a file to the transaction

{
    "status": "errors",
    "errors": [
        {
            "field": "files",
            "description": "File:  is size 0, please submit a valid file."
        }
    ]
}

When some `payerAddress` information is missing in a Solicited attachments transaction

{
    "status": "errors",
    "errors": [
        {
            "field": "payerAddress.state",
            "description": "must not be blank"
        },
        {
            "field": "payerAddress.address1",
            "description": "must not be blank"
        },
        {
            "field": "payerAddress.city",
            "description": "must not be blank"
        }
    ]
}

You can receive one or more error instances depending on which fields are missing.

When the entire block of `payerAddress` information is missing

{
    "status": "errors",
    "errors": [
        {
            "field": "tradingPartnerServiceId",
            "description": "trading partner not established for digital attachments, please provide a payerFaxNumber or payerAddress"
        }
    ]
}

This error can occur if there is a mistake in the payer address or other information.

When you have a typo in the `controlNumber`, or a missing digit in this value, you'll see the following error

{
    "status": "errors",
    "errors": [
        {
            "field": "controlNumber",
            "description": "BAD_CONTROL_NUMBER, ControlNumber has to be 9 digits."
        }
    ]
}

If the `controlNumber` is missing entirely

{
    "status": "errors",
    "errors": [
        {
            "field": "controlNumber",
            "description": "must not be blank"
        },
        {
            "field": "controlNumber",
            "description": "BAD_CONTROL_NUMBER, ControlNumber has to be 9 digits."
        }
    ]
}

In this case, the API engine reports two errors.

Missing files in a Solicited transaction

These may appear in X12 EDI format. Such a message appears similar to the following:

{
    "status": "errors",
    "attachmentId": null,
    "errors": [
        {
            "field": "Segment: STC",
            "location": "Loop: 2000, Segment Position: 13",
            "description": "Required Segment Missing"
        }
    ],
    "transactionSetAcknowledgement" : "Rejected",
    "implementationTransactionSetSyntaxError" : "One or More Segments in Error"
}

Did this page help you?