jQuery Deferred reject() Method

What You’ll Learn

The reject() method marks a jQuery Deferred as failed. It runs fail() and catch() handlers with your error reason — and prevents done() from firing. This tutorial covers syntax, five examples, comparisons with resolve() and fail(), and when to reject vs resolve.

Introduction

Not every async task succeeds. Validation can fail, networks time out, and servers return errors. When you own a $.Deferred(), you signal failure by calling reject() — the mirror image of resolve() for success.

Listeners registered with fail() or catch() receive the rejection reason. Consumers holding only a promise() cannot call reject() — only the module that created the Deferred settles it.

Understanding the reject() Method

reject() transitions a pending Deferred into the rejected state. jQuery invokes every queued fail(), catch(), and always() handler with the arguments you pass to reject().

Once rejected, the state is permanent — you cannot resolve() the same Deferred afterward. done() handlers never run on a rejected Deferred.

📝 Syntax

General form of deferred.reject:

deferred.reject( [ args ] )

Parameters

• args (optional) — rejection reason(s) forwarded to fail() handlers: string, Error, object, or multiple values.

Return value

• Returns the same Deferred object for chaining (though state is now locked to rejected).

Basic reject + fail handler

const dfd = $.Deferred();

dfd.fail(function (error) {
  console.error("Error:", error);
});

dfd.reject("Operation failed: invalid input");

Examples Gallery

Each example shows when and how to call reject(). Use the Try-it links to run them interactively.

const dfd = $.Deferred();

dfd.fail(function (error) {
  console.error("Error:", error);
});

dfd.reject("Network timeout");

Error: Network timeout

const dfd = $.Deferred();

dfd.done(function (message) {
  console.log("Success:", message);
}).fail(function (error) {
  console.error("Error:", error);
});

setTimeout(function () {
  const conditionMet = false;

  if (conditionMet) {
    dfd.resolve("Operation completed successfully.");
  } else {
    dfd.reject("Operation failed: Condition not met.");
  }
}, 500);

Error: Operation failed: Condition not met.

function settle(ok) {
  const dfd = $.Deferred();

  dfd.done(function (v) { console.log("resolved:", v); });
  dfd.fail(function (e) { console.log("rejected:", e); });

  if (ok) {
    dfd.resolve("OK");
    dfd.reject("Too late");  // ignored — already resolved
  } else {
    dfd.reject("Failed");
    dfd.resolve("Too late"); // ignored — already rejected
  }
}

settle(false);  // rejected: Failed

rejected: Failed

const dfd = $.Deferred();

dfd.fail(function (status, message, code) {
  console.log(status, message, "(" + code + ")");
});

dfd.reject(404, "Not found", "ERR_404");

404 Not found (ERR_404)

function saveUser(name) {
  const dfd = $.Deferred();

  if (!name || name.length < 2) {
    dfd.reject("Name must be at least 2 characters");
  } else {
    dfd.resolve({ saved: true, name: name });
  }

  return dfd.promise();
}

saveUser("A").catch(function (err) {
  console.error("Save failed:", err);
});

Save failed: Name must be at least 2 characters

🚀 Use Cases

• Input validation — reject when form data fails checks before sending to the server.
• Failed AJAX — wrap XHR errors and call reject() in custom Deferred-based helpers.
• Aborted operations — reject when the user cancels a long task.
• Business rule failures — reject when server logic returns an error payload you treat as failure.
• Promise chains — reject propagates to downstream fail() / catch() handlers.

📝 Notes

• Only call reject() on Deferreds you own — not on promises returned to you.
• Always pair public async APIs with consumer-side fail() or catch().
• Use descriptive rejection reasons — strings, Error objects, or structured data.
• state() returns "rejected" after reject (preferred over deprecated isRejected() in jQuery 3+).
• For custom this in fail handlers, use rejectWith() next.

💡 Best Practices