Handling Errors in Attachment Submissions transactions

The Attachments Submission API provides useful error information with HTTP 400 code 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.

When submitterId is not passed in the headers

This can occur if submitterId is not present in the Apigee settings or is not passed in a custom header. The submitter may need to work with the implementation team to get more details.

```json 
{
    "status": "errors",
    "errors": [
        {
            "field": "submitterId",
            "description": "Unable to process the request at this time. Valid SubmitterId value must be passed"
        }
    ]
}
```

Specifying the wrong payer

If you accidentally specify the wrong payer, or a payer that does not support digital attachment capabilities, you will see the following error:

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

The tradingPartnerName is a required attribute for all Attachment Submission requests. If you omit this value in the JSON header object, you will receive the following error:

```json
{
    "status": "errors",
    "errors": [
        {
            "field": "tradingPartnerName",
            "description": "must not be blank"
        }
    ]
}
```

When you forget to attach a file to the transaction

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

When you attached a file containing virus

```json
{
    "status": "errors",
    "errors": [
        {
            "field": "files",
            "description": "Invalid document found, possible virus detected"
        }
    ]
}
```

When some payerAddress information is missing in a Solicited attachments transaction

```json
{
    "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

```json
{
    "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 will see the following error

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

If the controlNumber is missing entirely

```json
{
    "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:

```json
{
    "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"
}
```

When invalid characters are sent in the request

This error can occur if *, ~, ^, or : characters are sent in the request:

```json
{
    "status": "errors",
    "errors": [
        {
            "field": "tradingPartnerName",
            "description": "*, ~, ^, : characters are not allowed"
        }
    ]
}
```

When file type is not supported

```json 
{
    "status": "errors",
    "errors": [
        {
            "field": "file",
            "description": "Unsupported File Type: (text/html). Please Use application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/docx,  text/plain, text/rtf, application/rtf, application/xml, image/jpeg, image/gif, image/png, image/tiff, image/bmp"
        }
    ]
}
```

Did this page help you?