jQuery .ajaxError() Method

What You’ll Learn

The .ajaxError() method is jQuery’s legacy shorthand for binding global ajaxError handlers on document. This tutorial covers $(document).ajaxError(handler), the handler signature (event, jqXHR, ajaxSettings, thrownError), why binding must target document since 1.9, migration to .on("ajaxError") and cleanup with .off("ajaxError"), and why the method is deprecated since jQuery 3.5. Unlike .click(), there is no trigger variant — only binding. The handler fires only on Ajax errors, not success. For the modern ajaxError event API, see the jQuery ajaxError event tutorial.

Introduction

Before jQuery 1.7 unified events with .on() and .off(), global Ajax events had matching shorthand methods — .ajaxStart(), .ajaxSend(), .ajaxError(), and others. The .ajaxError(handler) method let you register a page-wide “request failed” callback in one short call: $(document).ajaxError(function(){ ... }). It has been available since jQuery 1.0 and remains in jQuery 3.x for backward compatibility but is marked deprecated since 3.5.

Understanding .ajaxError() matters when reading older admin panels, legacy jQuery plugins, and tutorials written before .on("ajaxError") became standard. Unlike DOM event shorthands such as .click(), .ajaxError() has only a binding form — there is no no-argument trigger variant. The handler runs only when a request fails — successful responses trigger ajaxSuccess instead. Modern jQuery binds the same global event explicitly: $(document).on("ajaxError", handler). This page documents the shorthand API and shows how to migrate.

Understanding the .ajaxError() Method

The official jQuery API describes .ajaxError() as a way to register a handler to be called when Ajax requests complete with an error. When you pass a function, jQuery registers it on document and calls it after every qualifying failed Ajax request — HTTP errors, transport failures, or parser errors. That is the same ajaxError global event that .on("ajaxError") handles today.

The handler receives four arguments even though the API signature lists only handler: event (the jQuery event object), jqXHR (the XMLHttpRequest wrapper — read jqXHR.status for the HTTP code), ajaxSettings (the settings object passed to $.ajax()), and thrownError (the textual portion of the HTTP status, such as “Not Found” for 404). Requests with global: false opt out — they do not trigger .ajaxError() handlers. Cross-domain script and cross-domain JSONP requests also do not trigger ajaxError.

📝 Syntax

The .ajaxError() method has one signature from the official jQuery API — binding only. There is no trigger form unlike .click():

1. Bind a handler — .ajaxError( handler ) (deprecated since 3.5)

$( document ).ajaxError( handler )

• handler — function invoked when any qualifying Ajax request fails. Official docs list Function(); the callback actually receives function( event, jqXHR, ajaxSettings, thrownError ) { ... }.
• Must attach to document since jQuery 1.9 — not window or other elements.
• Fires only on error — not on successful requests.
• Not called for cross-domain script or cross-domain JSONP requests.
• Returns the jQuery object (document wrapped) for chaining.
• Modern replacement: $( document ).on( "ajaxError", handler ).

2. Official jQuery API migration note

// Deprecated binding

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

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

} );



// Modern binding

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

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

} );



// Remove handler — use .off(), not .unbind()

$( document ).off( "ajaxError", myHandler );

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

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

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

Do not use deprecated .unbind("ajaxError") in new code. Store a named function reference when you need to remove a specific handler later.

Return value

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

Examples Gallery

Five examples cover basic binding with a failing request, reading thrownError and jqXHR.status, filtering by settings.url, migration from .ajaxError() to .on("ajaxError"), and removing handlers with .off(). Use the Try-it links to run each snippet in the browser. Remember: binding with .ajaxError(handler) is deprecated — these demos show legacy syntax you will encounter in older code.

$( document ).ajaxError( function() {

  $( ".log" ).text( "Handler ran via .ajaxError(function(){ ... })." );

} );



$( "#fetch" ).on( "click", function() {

  $.get( "https://httpbin.org/status/404" );

} );

User clicks #fetch → $.get() requests 404 URL



When request fails → .log shows handler message



Successful $.get() calls do NOT trigger .ajaxError()



Deprecated — prefer .on("ajaxError", fn) for new code

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

  $( ".log" ).text(

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

  );

} );



$( "#fetch" ).on( "click", function() {

  $.get( "https://httpbin.org/status/404" );

} );

404 request fails → .log shows "Status: 404 | thrownError: Not Found"



jqXHR.status is the numeric HTTP code



thrownError is the textual status portion

var targetUrl = "https://httpbin.org/status/404";



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

  if ( settings.url === targetUrl ) {

    $( ".log" ).text( "Filtered match — URL: " + settings.url );

  }

} );

404 on watched URL → .log shows filtered message



404 on other URL → handler runs but if-block skipped



Same filtering pattern works with .on("ajaxError")

// Legacy — deprecated since jQuery 3.5

$( document ).ajaxError( function() {

  $( "#out" ).text( "Legacy: .ajaxError(function(){ ... })." );

} );



// Modern — use for new code

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

  $( "#out" ).text( "Modern: .on('ajaxError', function(){ ... })." );

} );

Both handlers fire when a 404 $.get() fails



Legacy message from .ajaxError(fn)



Modern message from .on("ajaxError", fn)



Behavior is identical — only the API name differs

var count = 0;



function onError() {

  count++;

  $( ".log" ).text( "Handler active — ajaxError count: " + count );

}



$( document ).ajaxError( onError );



$( "#remove" ).on( "click", function() {

  $( document ).off( "ajaxError", onError );

  $( ".log" ).text( "Handler removed — count stays " + count + "." );

} );

Trigger 404 → count increments



Click Remove → .off("ajaxError", onError)



Next 404 still fails but handler no longer runs — count unchanged

🚀 Common Use Cases

• Reading legacy code — recognize $(document).ajaxError(fn) as equivalent to .on("ajaxError", fn) in older admin panels.
• Global error logging — legacy debug panels log failed requests via .ajaxError() — migrate to .on() when refactoring.
• Status inspection — read jqXHR.status and thrownError in a global handler for development logging.
• URL filtering — compare settings.url inside .ajaxError(fn) before updating the DOM.
• SPA teardown — remove global handlers with .off("ajaxError", fn) when unmounting a view.
• Third-party isolation — requests with global: false still opt out of .ajaxError() handlers.

📝 Notes

• Deprecated since jQuery 3.5 — do not use $(document).ajaxError(handler) in new code. Use .on("ajaxError") instead. Available since jQuery 1.0.
• Attach to document since jQuery 1.9 — not window or other elements.
• Binding only — no no-argument trigger form unlike .click() or .mousedown().
• Handler receives (event, jqXHR, ajaxSettings, thrownError) even though the API lists handler as Function().
• Fires only on error — successful requests trigger ajaxSuccess, not ajaxError.
• Not called for cross-domain script or cross-domain JSONP requests.
• Remove handlers with $(document).off("ajaxError", handler) — not .unbind("ajaxError").
• Requests with global: false do not trigger .ajaxError() handlers.
• Legacy code using .ajaxError() still runs in jQuery 3.x — migrate when you refactor those files.
• For event order, comparison with .fail(), and the complete modern workflow, see the jQuery ajaxError event tutorial.

💡 Best Practices