.ajaxError()


.ajaxError( handler )Returns: jQuery

Description: Register a handler to be called when Ajax requests complete with an error. This is an Ajax Event.

Whenever an Ajax request completes with an error, jQuery triggers the ajaxError event. Any and all handlers that have been registered with the .ajaxError() method are executed at this time. Note: This handler is not called for cross-domain script and cross-domain JSONP requests.

To observe this method in action, set up a basic Ajax load request.

1
2
3
<button class="trigger">Trigger</button>
<div class="result"></div>
<div class="log"></div>

Attach the event handler to the document:

1
2
3
$( document ).ajaxError(function() {
$( ".log" ).text( "Triggered ajaxError handler." );
});

Now, make an Ajax request using any jQuery method:

1
2
3
$( "button.trigger" ).on( "click", function() {
$( "div.result" ).load( "ajax/missing.html" );
});

When the user clicks the button and the Ajax request fails, because the requested file is missing, the log message is displayed.

All ajaxError handlers are invoked, regardless of what Ajax request was completed. To differentiate between the requests, use the parameters passed to the handler. Each time an ajaxError handler is executed, it is passed the event object, the jqXHR object (prior to jQuery 1.5, the XHR object), and the settings object that was used in the creation of the request. When an HTTP error occurs, the fourth argument (thrownError) receives the textual portion of the HTTP status, such as "Not Found" or "Internal Server Error." For example, to restrict the error callback to only handling events dealing with a particular URL:

1
2
3
4
5
$( document ).ajaxError(function( event, jqxhr, settings, thrownError ) {
if ( settings.url == "ajax/missing.html" ) {
$( "div.log" ).text( "Triggered ajaxError handler." );
}
});

Additional Notes:

  • As of jQuery 1.9, all the handlers for the jQuery global Ajax events, including those added with the .ajaxError() method, must be attached to document.
  • If $.ajax() or $.ajaxSetup() is called with the global option set to false, the .ajaxError() method will not fire.

Example:

Show a message when an Ajax request fails.

1
2
3
$( document ).ajaxError(function( event, request, settings ) {
$( "#msg" ).append( "<li>Error requesting page " + settings.url + "</li>" );
});