jquery / jquery/api.jquery.com

`.ajax()` documentation unclear about expectations/data type for `errorThrown`

Open
#1,113 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
HTML
Stars
325
Forks
260
PR merge metrics
No merged PRs in 30d

Description

Migrated from jQuery repo: https://github.com/jquery/jquery/issues/4211

Description

There is a seeming contradiction in the documentation for $.ajax().

The docs for the error setting of this function indicate:

... The function receives three arguments: The jqXHR (in jQuery 1.4.x, XMLHttpRequest) object, a string describing the type of error that occurred and an optional exception object, if one occurred...

But later the same docs indicate:

... When an HTTP error occurs, errorThrown receives the textual portion of the HTTP status, such as "Not Found" or "Internal Server Error." ...

In addition, the docs indicate that the type of the parameter is String. But, based on the first sentence, it sounds like it can be either an object or a string; which is it?

Separately, it appears that the errorThrown will always be an empty string for HTTP errors that occur when using HTTP/2 (aka H2). This appears to be because statusText is always an empty string for an HTTP/2 request (more info: https://stackoverflow.com/questions/41632077/why-is-the-statustext-of-my-xhr-empty).

I'd love it for the jQuery team to weigh-in on both of these limitations in the current docs.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the $.ajax() documentation, especially the error setting and its errorThrown parameter description. Reconcile the cited statements about the parameter's type and document the HTTP/2 empty statusText limitation; the work is done when the expected value and limitation are unambiguous.

Written by the indexing model from the issue text.

Assessment

Tech stack
jquery
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.