Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

144 lines (99 sloc) 3.402 kb

errorq, a jQuery plugin

Robust error/retry queue for Ajax requests.

The Internet is super flaky, especially "cloud services" like Google App Engine. This plugin turns any DOM element into a FIFO queue of Ajax requests that get retried when they fail. A non-successful response is any that triggers the error handler in a call to $.ajax().

This is a low-level library that should provide the hooks you need to display visual information for what's happening as Ajax requests are queued up and retried in the background. No CSS is required to use the plugin.


Get a singleton ErrorQ instance for your DOM node like this:

var errorq = $('#error-viewer').errorq();

Send a request which is tried immediately:

    url: '/myserver',
    type: 'POST',
    data: {foo: 'bar'},
    success: function(data, textStatus, jqXHR) {
        // do your success stuff
    error: function(jqXHR, textStatus, errorThrown) {
        // If you define your *own* error handler
        // then it will be called. If you're using errorq you probably
        // don't need one.

If the request fails then it gets retried after a couple seconds. You can keep queuing up requests and the failing ones will get retried in the order they were received.

The errorq instance is a singleton per DOM node but you can reconfigure it permanently like this:

var errorq = $('#error-viewer').errorq({property: 'value'});


Number of milleseconds to wait before retrying, defaults to 2000.
Number of retries before giving up on a request, defaults to 8.


To show visual feedback of what's going you'll probably want to bind functions to custom ErrorQ events. All events are namespaced but as a shortcut you can bind like this:

errorq.bind('<name>', function(event, work) {
    // handle event...


When handling events you get access to a simple Work object that contains information about the work queued up.


Tell the request to abort (if in progress) and remove it from the retry queue.

Numeric ID unique to the page. Suitable for creating DOM ids if you use a prefix.
The same settings you passed to errorq.ajax(settings)
true if this request was successful.
true if this request was aborted either by the user or by hitting the max number of retries
Number of tries so far.
ErrorQ instance that created this Work object.


fired for each request failure, even after a retry.

errorq.bind('error', function(event, work) {
    // handle event...


fired when a request finishes successfully.

errorq.bind('success', function(event, work) {
    // handle event...


fired when a request is aborted either via work.abort() or by maxing out the number of retries.

errorq.bind('abort', function(event, work) {
    // handle event...


To run the tests open tests/index.html in your favorite web browser. The test suite is powered by QUnit

Jump to Line
Something went wrong with that request. Please try again.