When should XMLHttpRequest's onerror handler fire

I have a little problem understanding XMLHttpRequest's handlers. The specification says this about the onerror handler:

error [Dispatched ... ] When the request has failed.

load [Dispatched ... ] When the request has successfully completed.

The problem is, what does it mean that "the request has failed". That could be

• the request couldn't be issued at all (eg. Connection refused and such errors), or
• the above plus the server returned an error code (eg. 404)

Also, I'd like to know whether it means onerror and onload should never fire simultaneously.

This reference indicates the onerror handler should be executed depending on the status code and onload depending on readyState. That would indicate they are not mutually exclusive, however, I don't think this is an authoritative information.

I'm asking because using the latest Opera snapshot, I found onload is fired even on 404 status code. I know testing status is a sure bet, but I'd like to know whether it's something I have to do per specification or just a workaround for a bug in Opera.

Solution 1:

As mentioned in the comments, onerror fires when there is a failure on the network level. If the error only exists on the application level, e.g., an HTTP error code is sent, then onload still fires. You need to test the returned status code explicitly in your onreadystatechange handler.

Note that a denied cross-domain request will also fire the onerror handler.

Solution 2:

In addition to apsillers' answer, note that XMLHttpRequest handles redirects automatically in the background, so you don't have to check for this reply codes in the onload event (this event will be invoked only once - on the final call). Also note, that in case you send payload data with the POST method and if the requests is redirected, XMLHttpRequest change the method from POST to GET and discards any payload data for security reasons. The onload event will still be invoked but you will need to re-send your request manually again to the new destination.