superagent

SuperAgent treats 4xx and 5xx responses (and unhandled 3xx responses) as errors by default.

Error Object Properties

When an HTTP error occurs, the error object contains:

• err.status: The HTTP status code (e.g., 404).
• err.response: An object containing all response properties.

Note: Network failures or timeouts do not contain err.status or err.response.

Customizing Error Logic with .ok()

If you want to treat certain status codes as successful (e.g., treating a 404 as a valid response), use the .ok(callback) method. The callback receives the response and should return true if the response should be considered a success.

// Checking status manually
if (err && err.status === 404) {
  alert('oh no ' + res.body.message);
}

// Using .ok() to redefine success
request.get('/404')
  .ok(res => res.status < 500)
  .then(response => {
    // 404 is now treated as a successful response
  })

An Agent is a persistent instance of SuperAgent that can maintain state.

• Cookie Persistence (Node.js): In Node, SuperAgent does not save cookies by default. Use request.agent() to create an agent that maintains a separate cookie jar for all requests made through it.
• Browser Behavior: In the browser, cookies are managed by the browser itself, so .agent() does not provide isolation.
• Default Options: Any configuration applied to an agent (via use, auth, set, query, etc.) will be applied to every request made by that agent.

Supported configuration methods on Agents: use, on, once, set, query, type, accept, auth, withCredentials, sortQuery, retry, ok, redirects, timeout, buffer, serialize, parse, ca, key, pfx, cert.

const agent = request.agent();
agent
  .post('/login')
  .then(() => {
    return agent.get('/cookied-page');
  });

SuperAgent considers 4xx and 5xx responses (and unhandled 3xx responses) as errors by default.

Error Object Properties

When an error occurs, the error object contains:

• err.status: The HTTP status code (e.g., 404, 500).
• err.response: The full response object.

Customizing Error Logic

If you want to treat certain error status codes as successful responses, use the .ok(callback) method. The callback receives the response and should return true if it should be treated as a success.

Handling Errors in Callbacks

Callbacks receive two arguments: (error, response). If no error occurred, the first argument is null.

// Customizing what is considered an 'ok' response
request.get('/404')
  .ok(res => res.status < 500)
  .then(response => {
    // 404 is now treated as a successful response
  });

// Checking specific error status
if (err && err.status === 404) {
  alert('oh no ' + res.body.message);
}

You can initiate requests using method names on the request object (e.g., .get(), .post(), .put(), .del(), .head(), .patch()) or by passing the method as a string to request(). Requests can be sent using Promises (.then(), .catch()), the .end() callback (not recommended), or await.

Common HTTP Methods:

• GET (default)
• POST
• PUT
• DELETE (use .del() for IE compatibility)
• HEAD
• PATCH

Response and Error handling:

• Success response: res.body, res.headers, res.status
• Error response: err.message, err.response

// Using Promise/await
request
  .get('/search')
  .then(res => {
     console.log(res.body, res.headers, res.status);
  })
  .catch(err => {
     console.log(err.message, err.response);
  });

// Using string method
request('GET', '/search').then(success, failure);

// Using callback (not recommended)
request('GET', '/search').end(function(err, res){
  if (res.ok) {}
});

In Node.js, you can use superagent with callbacks, promises (.then/.catch), or async/await.

Common methods include:

• .post(url): Initiates a POST request.
• .send(data): Sends a JSON post body.
• .set(name, value): Sets HTTP request headers.
• .end(callback): Sends the request and executes a callback (for the callback pattern).
• .query(data): Adds query string parameters to the request.

const superagent = require('superagent');

// callback
superagent
  .post('/api/pet')
  .send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
  .set('X-API-Key', 'foobar')
  .set('accept', 'json')
  .end((err, res) => {
    // Calling the end function will send the request
  });

// promise with then/catch
superagent.post('/api/pet').then(console.log).catch(console.error);

// promise with async/await
(async () => {
  try {
    const res = await superagent.post('/api/pet');
    console.log(res);
  } catch (err) {
    console.error(err);
  }
})();