The AWS SDK for JavaScript v2 has reached end-of-support. We recommend that you migrate to AWS SDK for JavaScript v3. For additional details and information on how to migrate, please refer to this announcement.

Using a Request Object Event Listener

If you do not create and pass an anonymous callback function as a parameter when you call a service object method, the method call generates an AWS.Request object that must be manually sent using its send method.

To process the response, you must create an event listener for the AWS.Request object to register a callback function for the method call. The following example shows how to create the AWS.Request object for calling a service object method and the event listener for the successful return.

// create the AWS.Request object
var request = new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances();

// register a callback event handler
request.on('success', function(response) {
  // log the successful data response
  console.log(response.data); 
});

// send the request
request.send();

After the send method on the AWS.Request object is called, the event handler executes when the service object receives an AWS.Response object.

For more information about the AWS.Request object, see Class: AWS.Request in the API Reference. For more information about the AWS.Response object, see Using the Response Object or Class: AWS.Response in the API Reference.

Chaining Multiple Callbacks

You can register multiple callbacks on any request object. Multiple callbacks can be registered for different events or the same event. Also, you can chain callbacks as shown in the following example.

request.
  on('success', function(response) {
    console.log("Success!");
  }).
  on('error', function(response) {
    console.log("Error!");
  }).
  on('complete', function() {
    console.log("Always!");
  }).
  send();

Request Object Completion Events

The AWS.Request object raises these completion events based on the response of each service operation method:

You can register a callback function in response to any of these events. For a complete list of all request object events, see Class: AWS.Request in the API Reference.

The success Event

The success event is raised upon a successful response received from the service object. Here is how you register a callback function for this event.

request.on('success', function(response) { 
  // event handler code
});

The response provides a data property that contains the serialized response data from the service. For example, the following call to the listBuckets method of the Amazon S3 service object

s3.listBuckets.on('success', function(response) {
  console.log(response.data);
}).send();

returns the response and then prints the following data property contents to the console.

{ Owner: { ID: '...', DisplayName: '...' },
  Buckets: 
   [ { Name: 'someBucketName', CreationDate: someCreationDate },
     { Name: 'otherBucketName', CreationDate: otherCreationDate } ],
  RequestId: '...' }

The error Event

The error event is raised upon an error response received from the service object. Here is how you register a callback function for this event.

request.on('error', function(error, response) { 
  // event handling code
});

When the error event is raised, the value of the response's data property is null and the error property contains the error data. The associated error object is passed as the first parameter to the registered callback function. For example, the following code:

s3.config.credentials.accessKeyId = 'invalid';
s3.listBuckets().on('error', function(error, response) {
  console.log(error);
}).send();

returns the error and then prints the following error data to the console.

{ code: 'Forbidden', message: null }

The complete Event

The complete event is raised when a service object call has finished, regardless of whether the call results in success or error. Here is how you register a callback function for this event.

request.on('complete', function(response) { 
  // event handler code
});

Use the complete event callback to handle any request cleanup that must execute regardless of success or error. If you use response data inside a callback for the complete event, first check the response.data or response.error properties before attempting to access either one, as shown in the following example.

request.on('complete', function(response) {
  if (response.error) {
    // an error occurred, handle it
  } else {
    // we can use response.data here
  }
}).send();

Request Object HTTP Events

The AWS.Request object raises these HTTP events based on the response of each service operation method:

You can register a callback function in response to any of these events. For a complete list of all request object events, see Class: AWS.Request in the API Reference.

The httpHeaders Event

The httpHeaders event is raised when headers are sent by the remote server. Here is how you register a callback function for this event.

request.on('httpHeaders', function(statusCode, headers, response) {
  // event handling code
});

The statusCode parameter to the callback function is the HTTP status code. The headers parameter contains the response headers.

The httpData Event

The httpData event is raised to stream response data packets from the service. Here is how you register a callback function for this event.

request.on('httpData', function(chunk, response) {
  // event handling code
});

This event is typically used to receive large responses in chunks when loading the entire response into memory is not practical. This event has an additional chunk parameter that contains a portion of the actual data from the server.

If you register a callback for the httpData event, the data property of the response contains the entire serialized output for the request. You must remove the default httpData listener if you don't have the extra parsing and memory overhead for the built-in handlers.

The httpUploadProgress and httpDownloadProgress Events

The httpUploadProgress event is raised when the HTTP request has uploaded more data. Similarly, the httpDownloadProgress event is raised when the HTTP request has downloaded more data. Here is how you register a callback function for these events.

request.on('httpUploadProgress', function(progress, response) {
  // event handling code
})
.on('httpDownloadProgress', function(progress, response) {
  // event handling code
});

The progress parameter to the callback function contains an object with the loaded and total bytes of the request.

The httpError Event

The httpError event is raised when the HTTP request fails. Here is how you register a callback function for this event.

request.on('httpError', function(error, response) {
  // event handling code
});

The error parameter to the callback function contains the error that was thrown.

The httpDone Event

The httpDone event is raised when the server finishes sending data. Here is how you register a callback function for this event.

request.on('httpDone', function(response) {
  // event handling code
});