Understanding Integration Gateway Error Handling

Error handling is an integration gateway service that assists connectors to manage errors that occur during processing. Errors on the integration gateway are handled by target connectors and listening connectors.

This section discusses:

  • Target connector error handling.

  • Listening connector error handling.

  • Integration gateway exception types.

The Target Connector Interface (TCI) specifies the methods that target connectors must implement for the integration gateway to manage them. These methods include a set of standard exceptions that target connectors generate when they experience errors during processing.

Listening connectors or the gateway manager catch these exceptions and provide an appropriate implementation for each. When the source of the message is an integration engine, the gateway manager catches the exceptions. Otherwise, listening connectors are responsible for handling exceptions that are generated during processing.

Unlike target connectors, listening connectors are not managed by the gateway manager and, therefore, do not adhere to any interface. However, a listening connector must invoke the gateway manager to pass a message from the integration gateway to the integration engine.

The gateway manager has predefined exceptions.

In general, exceptions are thrown in a target connector and caught by a listening connector. As a result, a listening connector must catch these exceptions and handle them as appropriate. Typically, the listening connector generates an error message and sends it back to the requester.

This section discusses integration gateway exception types.

Standard Exceptions

The following standard error and exception types are handled by the integration gateway, target connectors, and listening connectors:

Exception Type



A target connector attempted to process a message that has already been processed. This is usually discovered based on an error that is attained from the external system that is being contacted.

Of the connectors that are delivered with the PeopleSoft software, only the PeopleSoft 8.1 target connector (PSFT81TARGET) can generate this exception. Target connectors are not required to generate this exception.


The message reached its intended destination but could not be processed.

Determining that the destination could not process a message requires significant knowledge of the destination system, which a target connector might not have. Whenever possible, a target connector should attempt to determine this situation; otherwise this task must be decentralized and handled outside of the integration gateway.

For example, the HTTP target connector (HTTPTARGET) generates this exception when the external system returns an HTTP system code of 500.


The target connector cannot establish a connection with the intended destination. This is one of the most common exceptions.

When this exception is thrown during an asynchronous transaction, PeopleSoft Integration Broker tries to resend the message until successful.


A general error occurred.


A connector or the gateway manager determined that the message cannot be processed because of missing or erroneous information in a request or response.


A gateway service’s attempt to get information from an IBRequest or IBResponse failed. This can occur when the gateway services attempt to access a content section of a document by using an out-of-range index from one of the following methods:

  • GetContentSectionAt(index)

  • GetContentSectionInfoAt(index)

  • RemoveContentSectionAt(index)

If you try to access IBRequest or IBResponse with an out-of-range index by using any of these methods, this exception is thrown automatically and processing is interrupted.


A gateway service’s attempt to build an IBRequest or IBResponse failed. Failure can occur when:

  • Instantiating an IBRequest or IBResponse from a Multipurpose Internet Mail Extensions (MIME) format where the message that was sent does not comply with the PeopleSoft MIME format.

  • Instantiating an IBRequest by using the PS_XML format and passing an invalid PS_XML message.

    This is typically from the HTTP listening connector.

  • Setting invalid values to methods, such as setTransactionID or setMessageType.

These failures cause the integration gateway to generate this exception automatically and processing is interrupted.

Java Exceptions

Target connectors and listening connectors can handle miscellaneous Java exceptions, such as NullPointerException and ArrayOutOfBoundsException.