jQuery .ajaxError() Method

Beginner
Deprecated since 3.5
7 min read
Updated: Oct 2026
5 examples
Live preview
Definition

What Is .ajaxError()?

.ajaxError(handler) is jQuery’s legacy shorthand (since 1.0) for binding a global handler that runs when any qualifying Ajax request fails. Attach it to document. Unlike .click(), there is no no-argument trigger form — binding only.

Remember
// Deprecated shorthand
$(document).ajaxError(function (event, jqXHR, settings, thrownError) {
  // runs only when a qualifying Ajax request fails
});

// Modern replacement
$(document).on("ajaxError", handler);

// Opt out for one call:
$.ajax({ url: "/x", global: false });
NeedUse
Legacy global error bind$(document).ajaxError(fn) ⚠
Modern global error bind$(document).on("ajaxError", fn)
Success onlyajaxSuccess
Always (success or error)ajaxComplete
One request only$.ajax(...).fail(fn)
Approach

How to Use .ajaxError()

Recognize the legacy bind, know the handler args, then migrate to .on().

  1. Attach the handler to document with .ajaxError(handler) (legacy) or .on("ajaxError", handler) (preferred).
  2. Trigger a failing request with $.ajax(), $.get(), $.post(), or .load().
  3. Read jqXHR.status and thrownError; optionally filter with settings.url.
  4. Remove handlers with $(document).off("ajaxError", handler) — not .unbind().
  5. Use global: false on requests that must stay silent.
PieceRequired?Role
documentYes (1.9+)Only valid bind target for global Ajax events
handlerYesfunction(event, jqXHR, settings, thrownError)
settings.urlOptionalFilter which failed requests you react to
global: falseOptionalSkip all global Ajax events for that call

Pseudocode

Pseudocode
bind ajaxError on document with handler(event, jqXHR, settings, thrownError)
  // legacy:  $(document).ajaxError(handler)
  // modern:  $(document).on("ajaxError", handler)

when a jQuery Ajax request finishes with an error:
    if request.global === false:
        do not fire ajaxError
        return

    // note: cross-domain script / JSONP do not fire ajaxError

    fire ajaxError
        for each registered handler:
            call handler(event, jqXHR, settings, thrownError)

    fire ajaxComplete next
    if no other global Ajax requests are active:
        fire ajaxStop
Reference

Cheat Sheet

Keep these facts handy while reading or migrating legacy error handlers.

TopicDetail
Legacy bind$(document).ajaxError(handler) ⚠ deprecated 3.5
Modern bind$(document).on("ajaxError", handler)
Unbind$(document).off("ajaxError" [, handler])
Signaturefunction(event, jqXHR, settings, thrownError)
WhenError only — not on success
SinceMethod 1.0 · document-only 1.9+ · deprecated 3.5
Status / textjqXHR.status · thrownError
Opt outglobal: false in $.ajax() / $.ajaxSetup()
Trigger formNone — bind only (unlike .click())
Try it

Live Preview

Run a failing $.get() and watch the legacy .ajaxError() handler update the log.

Live demo uses a public API. Needs network access. Binding uses deprecated .ajaxError() for teaching.

Result
Ready — pick an action and click Run.
Code

jQuery Examples

Short, copy-ready snippets. These show legacy .ajaxError() you will see in older code — prefer .on("ajaxError") for new work. Use Try It Yourself for a live editor.

Example 1 — Basic $(document).ajaxError(fn)

Canonical legacy pattern: log when any qualifying Ajax request fails.

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

$("#fetch").on("click", function () {
  $.get("https://httpbin.org/status/404");
});
Try It Yourself

How It Works

  1. Bind. .ajaxError(fn) registers the function on document.
  2. Click. $.get() starts a request that returns 404.
  3. Fail. jQuery triggers ajaxError — not ajaxSuccess.
  4. Update. The log confirms the legacy handler ran.

Example 2 — Read jqXHR.status and thrownError

The handler receives four arguments — use them for status code and status text.

jQuery
$(document).ajaxError(function (event, jqXHR, settings, thrownError) {
  $(".log").text(
    "Status: " + jqXHR.status + " | thrownError: " + thrownError
  );
});

$("#fetch").on("click", function () {
  $.get("https://httpbin.org/status/404");
});
Try It Yourself

How It Works

  1. Args. jQuery passes event, jqXHR, settings, and thrownError.
  2. Code. jqXHR.status is the numeric HTTP status (404 here).
  3. Text. thrownError holds status text such as "Not Found".
  4. Display. Combine both for a clear error message.

Example 3 — Filter by settings.url

Handlers run for every failed request — narrow them with the settings object.

jQuery
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 +
      " | status: " + jqXHR.status
    );
  }
});
Try It Yourself

How It Works

  1. Global. Every failed qualifying request invokes the handler.
  2. Compare. Check settings.url against the endpoint you care about.
  3. React. Update the UI only for the watched URL.
  4. Skip. Other failures leave your message alone.

Example 4 — Migrate to .on("ajaxError")

Both bind the same global event — .on() is the recommended API.

jQuery
// 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(){ ... }).");
});
Try It Yourself

How It Works

  1. Same event. .ajaxError(fn) delegates to .on("ajaxError", fn).
  2. Rename. Migration is usually a one-line API change.
  3. Cleanup. Pair modern binds with .off("ajaxError", fn).
  4. New code. Always prefer .on() / .off().

Example 5 — Remove Handler with .off("ajaxError")

Store a named function, then remove it with .off() — not deprecated .unbind().

jQuery
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 + ".");
});
Try It Yourself

How It Works

  1. Named fn. Anonymous handlers cannot be removed individually.
  2. Bind. .ajaxError(onError) registers that reference.
  3. Remove. .off("ajaxError", onError) drops exactly that handler.
  4. Avoid. Do not use deprecated .unbind("ajaxError") in new code.

Edge Cases & Pitfalls

Check these before relying on global Ajax error handlers.

deprecated

Shorthand is deprecated since 3.5

New code should use $(document).on("ajaxError", handler). The shorthand still works for legacy apps.

target

Bind on document only (1.9+)

Handlers on window or other elements will not receive global Ajax events.

scope

Error only — not success

Successful requests fire ajaxSuccess, not ajaxError. Use ajaxComplete when you need both.

jsonp

Cross-domain script / JSONP skip it

Per the jQuery API, ajaxError is not called for cross-domain script and cross-domain JSONP requests.

global

global: false stays silent

Those requests never trigger .ajaxError(). Per-request .fail() still works.

Compatibility

Browser Support

The .ajaxError() method has been part of jQuery since 1.0. Since 1.9, handlers must attach to document. Binding via .ajaxError(handler) is deprecated since 3.5 but still functional — prefer .on("ajaxError").

✓ Deprecated · jQuery 1.0+

jQuery .ajaxError()

Works wherever your loaded jQuery version runs. Prefer a current jQuery 3.x build and migrate bindings to .on('ajaxError'). Requires jQuery Ajax — fetch() and axios do not trigger jQuery global events.

100% With jQuery Ajax
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
.ajaxError() Legacy API

Bottom line: Safe in legacy jQuery projects. Migrate bindings to .on('ajaxError') and cleanup to .off('ajaxError') when updating code.

Analysis

Performance Notes

ApproachCostBest for
One filtered global error handlerCheapSite-wide error toasts / logging
Per-request .fail()CheapCleanup for a single call
Heavy DOM work on every errorExpensiveAvoid — filter by URL first

Global error handlers are fine when they stay light. Filter by URL before touching the DOM, and prefer .fail() for request-specific work.

Remember

Key Takeaways

  • Role: legacy global “request failed” bind — error only.
  • Bind: $(document).ajaxError(fn) on document only (1.9+) — deprecated since 3.5.
  • Args: (event, jqXHR, settings, thrownError) — use status + URL filter.
  • Migrate: .on("ajaxError") / .off("ajaxError") for new code.

One line: .ajaxError() is the deprecated shorthand for binding global Ajax error handlers on document — prefer .on("ajaxError").

Frequently Asked Questions

The .ajaxError(handler) method binds a global function that runs whenever any qualifying jQuery Ajax request completes with an error. Attach it to document: $(document).ajaxError(fn). It is deprecated since jQuery 3.5 — use $(document).on("ajaxError", handler) instead.
Yes. $(document).ajaxError(handler) is deprecated since jQuery 3.5 (available since 1.0). Prefer $(document).on("ajaxError", handler) for new code. Legacy bindings still work in jQuery 3.x; migrate when you touch those files. Remove handlers with $(document).off("ajaxError", handler).
ajaxError is a global Ajax event, not a DOM event on a specific element. Since jQuery 1.9, all global Ajax handlers must be bound to document. Use $(document).ajaxError(fn) (legacy) or $(document).on("ajaxError", fn) (modern).
Four: function(event, jqXHR, ajaxSettings, thrownError). Use jqXHR.status for the HTTP code and thrownError for status text (for example "Not Found" on 404). Failed requests trigger ajaxError; successful ones trigger ajaxSuccess instead.
Replace $(document).ajaxError(fn) with $(document).on("ajaxError", fn). Replace .unbind("ajaxError") with $(document).off("ajaxError", fn). Under the hood, .ajaxError(handler) already delegates to .on("ajaxError") — migration is a straight rename for simple bindings.
No. It runs only when a qualifying request fails (HTTP error, transport error, or parser error). Use ajaxSuccess for success-only, or ajaxComplete for both outcomes.

Next: ajaxSuccess Event

Learn the global handler that runs when a jQuery Ajax request succeeds.

ajaxSuccess event tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

8 people found this page helpful

jQuery ajaxError Event jQuery ajaxSuccess Event