jQuery ajaxError Event

What You’ll Learn

The ajaxError event fires when a qualifying jQuery Ajax request completes with an error — not on success. This tutorial covers binding on document with .on("ajaxError"), the handler signature (event, jqXHR, ajaxSettings, thrownError), filtering by ajaxSettings.url, reading jqXHR.status and thrownError, opting out with global: false, and comparing global events with per-request .fail().

Introduction

When your page loads data with $.ajax(), $.get(), $.post(), or .load(), jQuery broadcasts lifecycle events to listeners on document. The ajaxError event is your global “something went wrong” hook — it fires only when a request fails, such as a 404 Not Found, a 500 server error, or a network timeout.

The official jQuery API distinguishes the ajaxError event (bound with .on("ajaxError") since 1.7) from the deprecated .ajaxError() method used in older code. Unlike ajaxComplete, which runs for both success and failure, ajaxError is outcome-specific — successful requests trigger ajaxSuccess instead. On failed requests, ajaxError runs before ajaxComplete.

Understanding the ajaxError Event

ajaxError is classified as an AjaxEvent — a global event triggered by jQuery’s Ajax transport, not a DOM event on a specific element. Whenever an Ajax request completes with an error, jQuery triggers ajaxError on document. Handlers receive four arguments: the native event object, the jqXHR object (same as the XMLHttpRequest wrapper returned by $.ajax()), ajaxSettings — the plain settings object used to create that request — and thrownError, the HTTP status text such as “Not Found” or “Internal Server Error.”

Every registered ajaxError handler runs for every failed qualifying request. To react only to certain URLs, inspect ajaxSettings.url inside the handler. Note: this handler is not called for cross-domain script or cross-domain JSONP requests.

📝 Syntax

The modern jQuery API for the ajaxError global event:

1. Bind a handler — $(document).on("ajaxError" [, handler]) (since 1.7)

$( document ).on( "ajaxError", handler )

• handler — function invoked when any qualifying Ajax request fails: function( event, jqXHR, ajaxSettings, thrownError ) { ... }.
• event — the jQuery event object.
• jqXHR — the jqXHR / XMLHttpRequest object; read jqXHR.status for the HTTP status code.
• ajaxSettings — settings passed to $.ajax() (url, type, data, context, etc.).
• thrownError — textual HTTP status on HTTP errors, e.g. "Not Found" or "Internal Server Error".

2. Official demo — document handler + .load() to missing URL

$( document ).on( "ajaxError", function() {

  $( ".log" ).text( "Triggered ajaxError handler." );

} );



$( "button.trigger" ).on( "click", function() {

  $( "div.result" ).load( "ajax/missing.html" );

} );

3. Filter by URL — inspect ajaxSettings

$( document ).on( "ajaxError", function( event, jqxhr, settings, thrownError ) {

  if ( settings.url == "ajax/missing.html" ) {

    $( "div.log" ).text( "Triggered ajaxError handler." );

  }

} );

4. Unbind — $(document).off("ajaxError" [, handler])

$( document ).off( "ajaxError" );              // remove all ajaxError handlers

$( document ).off( "ajaxError", myHandler );   // remove one handler

5. Deprecated method — .ajaxError(handler)

// Deprecated — use .on("ajaxError") instead

$( document ).ajaxError( function( event, jqxhr, settings, thrownError ) {

  console.log( "Request failed:", settings.url, thrownError );

} );

The old .ajaxError(handler) binding method still works but is deprecated. Migrate to $(document).on("ajaxError", handler) for consistency with other events and reliable unbinding via .off().

Return value

• .on("ajaxError", handler) returns the jQuery object (document wrapped) for chaining.
• Handler return values are ignored by jQuery’s global Ajax event system.

Examples Gallery

Examples 1, 3, and 4 follow the official jQuery API documentation. Examples 2 and 5 extend those patterns with URL filtering and a comparison with .fail(). Use the Try-it links to run each snippet in the browser.

$( document ).on( "ajaxError", function() {

  $( ".log" ).text( "Triggered ajaxError handler." );

} );



$( "button.trigger" ).on( "click", function() {

  $( "div.result" ).load( "ajax/missing.html" );

} );

User clicks .trigger → .load() requests missing file



Request fails (404) → .log shows "Triggered ajaxError handler."



Successful .load() calls do NOT trigger ajaxError

$( document ).on( "ajaxError", function( event, jqxhr, settings, thrownError ) {

  if ( settings.url == "ajax/missing.html" ) {

    $( "div.log" ).text( "Triggered ajaxError handler." );

  }

} );

Failed request to ajax/missing.html → .log updated



Failed request to other URLs → handler runs but if-block skipped





Use settings.type, settings.context, or custom keys to filter further

$( document ).on( "ajaxError", function( event, request, settings ) {

  $( "#msg" ).append( " Error requesting page " + settings.url + " " );

} );

Each failing Ajax request → #msg gains " Error requesting page [url] "



Two parallel failures → two appended messages





Ideal for a simple error log or status strip

$( document ).on( "ajaxError", function( event, jqXHR, settings, thrownError ) {

  $( "#details" ).html(

    "Status: " + jqXHR.status + " — " + thrownError +

    " (URL: " + settings.url + ")"

  );

} );

404 request → Status: 404 — Not Found



500 request → Status: 500 — Internal Server Error





thrownError is the status text; jqXHR.status is the numeric code

var globalError = 0;

var perRequestFail = 0;



$( document ).on( "ajaxError", function() {

  globalError++;

  $( "#global-count" ).text( globalError );

} );



$( "#run-fail" ).on( "click", function() {

  $.ajax( "/api/missing" ).fail( function() {

    perRequestFail++;

    $( "#fail-count" ).text( perRequestFail );

  } );

  $.ajax( "/api/broken" ).fail( function() {

    perRequestFail++;

    $( "#fail-count" ).text( perRequestFail );

  } );

} );

Click #run-fail → two failing $.ajax() calls



globalError → +2 (one ajaxError per failed request)



perRequestFail → +2 (one .fail() per call)



Success request → ajaxError unchanged; .fail() not called

🚀 Common Use Cases

• Error logging — append failed URL and status to a debug panel for every Ajax error during development.
• Global toast notifications — show a user-friendly “Something went wrong” banner when any request fails, filtered by settings.url.
• Analytics hooks — send error timing, URL, and jqXHR.status to monitoring when ajaxError fires.
• Session expiry detection — watch for 401/403 responses globally and redirect to login.
• Third-party isolation — set global: false on widget requests so expected failures do not trigger your global ajaxError logic.
• Testing — assert that a test harness saw the expected number of failed requests via a global counter.

📝 Notes

• Bind with $(document).on("ajaxError", handler) since jQuery 1.7 — not the deprecated .ajaxError(handler) method.
• Since jQuery 1.9, attach global Ajax handlers to document — not window.
• ajaxError fires only on failure — successful requests trigger ajaxSuccess instead.
• On failed requests, ajaxError runs before ajaxComplete.
• Every registered handler runs for every failed qualifying request.
• Requests with global: false do not trigger ajaxError.
• Not called for cross-domain script or cross-domain JSONP requests.
• Read the HTTP code with jqXHR.status and the status text from thrownError.
• Differentiate requests with ajaxSettings.url, ajaxSettings.type, or custom settings properties.
• For per-request error handling, prefer $.ajax(...).fail(fn) over a global handler with heavy filtering.

💡 Best Practices