urlopen.open() error responses

The urlopen.open() API receives error codes that provide information to help you recover from some errors.

The urlopen.open() API can receive error information that can reveal problems with servers and connections. This information is found in the GatewayScript error object that is returned in the callback function. When an exception is encountered, the GatewayScript API that is running can catch the error and handle it as part of the action execution. The exception results in an error that is posted to the document processing runtime and logged to the logging infrastructure. Users can determine whether an error is encountered during the connection by testing the error object. If no error is found, you can read the status code, response message, and response headers.

The programming interface for error handling of response.readAsBuffer() and response.readAsBuffers() APIs follows the example for the response.readAsJSON() API:
var urlopen = require ('urlopen');

// open connection to target
urlopen.open("http://somserver", function (error, response) {
    // handle the error when connecting to target
    if (error) throw error;
    // populate json
    response.readAsJSON ( function (error, json) {
        // handle the error when reading from target or JSON parsing
        if (error) throw error;
        // write json to log
        console.log (json);
        // write json to output context
        session.output.write (json);
GatewayScript supports the errors that are provided by ECMA JavaScript and its own particular variety of errors. The GatewayScript ulropen.open() errors can be grouped by their general cause.
Connection errors
Errors that occur when GatewayScript attempts to establish a connection with the target of the urlopen.open() API.
  • Invalid ip/domain (host not found)
  • DNS Lookup failure
  • DNS Lookup ok, not listening on desired port
  • error SSL Backend certificate is not trusted
Options errors
Errors that occur due to incorrect content in the request options parameter of the urlopen.open() API.
  • Null connection options
  • Incorrect urlopen options: undefined
  • No target
  • Invalid port/URI (unknown service port)
  • Unsupported service/protocol
  • Incorrect urlopen options: target not a string
  • Incorrect urlopen options: invalid HTTP method
  • Incorrect urlopen options: invalid HTTP method object type
  • Incorrect urlopen options: invalid content type
API usage
Errors that are due to an incorrect urlopen.open() call.
  • Wrong number of params for the url open function
  • url open callback is not a function
Errors with the remote server
Errors that are due to condition detected by the urlopen.open() API.
  • Timeout error on url open