jQuery ajaxError Event

Beginner
8 min read
Updated: Oct 2026
5 examples
Live preview
Definition

What Is ajaxError?

ajaxError is a global AjaxEvent (since jQuery 1.0; .on() binding since 1.7). jQuery triggers it on document whenever a qualifying Ajax request fails. All registered handlers run.

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

// Order (on failure):
// ajaxError  →  ajaxComplete  →  (ajaxStop when idle)

// Opt out for one call:
$.ajax({ url: "/x", global: false });

// Not fired for cross-domain script / JSONP requests
NeedUse
Global “request failed”$(document).on("ajaxError", fn)
Success onlyajaxSuccess
Always finishedajaxComplete
One request only$.ajax(...).fail(fn)
Hide loading when idleajaxStop
Approach

How to Use ajaxError

Bind once on document, then any failing jQuery Ajax call can notify that handler.

  1. Attach the handler to document with .on("ajaxError", handler).
  2. Make requests with $.ajax(), $.get(), $.post(), or .load().
  3. Optionally filter with ajaxSettings.url (or other settings).
  4. Read jqXHR.status and thrownError for HTTP details.
  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, ajaxSettings, thrownError)
ajaxSettings.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, ajaxSettings, thrownError)

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

    if cross-domain script or JSONP:
        do not fire ajaxError
        return

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

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

Cheat Sheet

Keep these facts handy while wiring global Ajax error handling.

TopicDetail
Bind$(document).on("ajaxError", handler)
Unbind$(document).off("ajaxError" [, handler])
Signaturefunction(event, jqXHR, ajaxSettings, thrownError)
WhenFailed requests only (not success)
SinceEvent 1.0 · .on() form 1.7 · document-only 1.9+
Status codejqXHR.status (e.g. 404, 500)
Status textthrownError (e.g. "Not Found")
Filterif (ajaxSettings.url === "...")
Opt outglobal: false in $.ajax() / $.ajaxSetup()
Try it

Live Preview

Trigger a real failing request and watch the global ajaxError handler update the log.

Live demo uses public HTTP APIs. Needs network access.

Result
Ready — pick an action and click Run.
Code

jQuery Examples

Short, copy-ready snippets. Open DevTools Console, or use Try It Yourself for a live editor.

Example 1 — Document Handler + Failing .load()

Official pattern: log a message when an Ajax request fails after a click.

jQuery
$(document).on("ajaxError", function () {
  $(".log").text("Triggered ajaxError handler.");
});

$(".trigger").on("click", function () {
  $(".result").load("ajax/missing.html");
});
Try It Yourself

How It Works

  1. Bind. .on("ajaxError") on document listens globally.
  2. Click. .load() starts an Ajax request under the hood.
  3. Fail. When the request errors, every ajaxError handler runs.
  4. Update. The log text confirms the global error event fired.

Example 2 — Filter by settings.url

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

jQuery
$(document).on("ajaxError", function (event, jqxhr, settings, thrownError) {
  if (settings.url === "ajax/missing.html") {
    $("div.log").text("Triggered ajaxError handler.");
  }
});
Try It Yourself

How It Works

  1. Args. jQuery passes event, jqxhr, settings, and thrownError.
  2. Compare. Check settings.url against the endpoint you care about.
  3. Act. Update UI only for matching failures.
  4. Skip. Non-matching failed URLs leave your UI alone.

Example 3 — Append “Error requesting page”

Official demo: append a short error string with the failed URL.

jQuery
$(document).on("ajaxError", function (event, request, settings) {
  $("#msg").append(" Error requesting page " + settings.url + " ");
});
Try It Yourself

How It Works

  1. Global. One handler covers every qualifying failed Ajax call.
  2. Append. Each failure adds another status fragment with the URL.
  3. Count. Parallel failures each fire their own ajaxError.
  4. Use. Handy for a simple error strip or debug log.

Example 4 — Read jqXHR.status and thrownError

HTTP failures expose a numeric status and textual status message.

jQuery
$(document).on("ajaxError", function (event, jqXHR, settings, thrownError) {
  $("#details").text(
    "status " + jqXHR.status + " — " + thrownError +
    " (" + settings.url + ")"
  );
});

// 404 → status 404 — Not Found
// 500 → status 500 — Internal Server Error
Try It Yourself

How It Works

  1. Code. jqXHR.status is the numeric HTTP status.
  2. Text. thrownError is the status text (e.g. "Not Found").
  3. URL. settings.url identifies which request failed.
  4. Display. Combine them for a clear error message.

Example 5 — ajaxError vs .fail()

Global event sees every failure; .fail() is tied to one call.

jQuery
var globalCount = 0;
var failCount = 0;

$(document).on("ajaxError", function () {
  globalCount++;
});

$.ajax("/missing-a").fail(function () { failCount++; });
$.ajax("/missing-b").fail(function () { failCount++; });

// After both fail:
// globalCount === 2, failCount === 2
// but each .fail() only saw its own request
Try It Yourself

How It Works

  1. Global. One ajaxError handler counts every failed request.
  2. Local. Each .fail() only increments for its own jqXHR.
  3. Same totals. Counts can match, but the scope is different.
  4. Choose. Site-wide error UI → global event; one call’s handling → .fail().

Edge Cases & Pitfalls

Check these before relying on global Ajax error handlers in production.

target

Bind on document only (1.9+)

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

scope

Errors only — not success

ajaxError skips successful responses. Use ajaxSuccess or ajaxComplete when you need those cases.

jsonp

Cross-domain script / JSONP skip it

Official docs: this handler 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

ajaxError has been part of jQuery since 1.0. Prefer $(document).on("ajaxError", …) (1.7+). Since 1.9, handlers must attach to document.

✓ Stable · jQuery 1.0+

jQuery ajaxError

Works in every browser that runs your loaded jQuery version. Prefer a current jQuery 3.x build for modern projects.

100% jQuery Ajax event
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 Universal

Bottom line: Safe for everyday apps. Bind on document, read status + thrownError, and use global: false for silent background calls.

Analysis

Performance Notes

ApproachCostBest for
One filtered ajaxErrorCheapSite-wide error toasts / logging
Per-request .fail()CheapError handling for a single call
Heavy DOM work every errorExpensiveAvoid — filter or debounce

Global 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: global “request failed” hook — not success.
  • Bind: $(document).on("ajaxError", fn) — document only since 1.9.
  • Details: jqXHR.status + thrownError; filter with ajaxSettings.url.
  • Local alternative: use .fail() for one-request error handling.

One line: ajaxError is jQuery’s global failure Ajax event — bind it on document.

Frequently Asked Questions

ajaxError is a global AjaxEvent that fires whenever a qualifying jQuery Ajax request completes with an error — HTTP failures, transport errors, or parser errors. Bind it with $(document).on("ajaxError", handler) (since 1.7). Every registered handler runs for every failed request.
Since jQuery 1.9, all global Ajax event handlers must be bound to document — not window or other elements. Use $(document).on("ajaxError", fn) and remove with $(document).off("ajaxError", fn).
No. ajaxError runs only when a request fails. Successful responses trigger ajaxSuccess instead. Both are followed by ajaxComplete. Use ajaxError for global error UI; use ajaxSuccess when you only care about success.
ajaxError is a global document event — one handler observes every qualifying failed request on the page. fail() is per-request on the jqXHR from $.ajax() — it runs only for that call. Use global events for site-wide error UI; use fail() for request-specific handling.
When $.ajax() or $.ajaxSetup() sets global: false, that request opts out of all global Ajax events. ajaxError will not fire for it. Per-request fail() and always() still run.
The fourth handler argument, thrownError, receives the textual portion of the HTTP status when an HTTP error occurs — for example "Not Found" for 404 or "Internal Server Error" for 500. Pair it with jqXHR.status (the numeric code).
The shorthand method .ajaxError(handler) is deprecated as of jQuery 3.5. Prefer $(document).on("ajaxError", handler) — the event API this page teaches.

Next: .ajaxError() method

See the deprecated shorthand and how to migrate to .on("ajaxError").

.ajaxError() 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)

9 people found this page helpful

jQuery .ajaxSend() Method jQuery .ajaxError() Method