Got HTTP Client: Making HTTP Requests Actually Enjoyable

I'll never forget the day I spent three hours debugging a simple API call. The error? My request library silently swallowed a redirect loop, and I had no idea what was happening under the hood. That's when I discovered Got, and honestly, it changed how I think about HTTP requests in Node.js.

Got isn't just another HTTP client—it's what happens when developers get tired of wrestling with low-level APIs and decide to build something that actually respects your time and sanity.

Table of Contents

• Setup and Installation
• 5 Essential Patterns You'll Use Daily
• Performance Comparison
• 3 Mistakes That'll Bite You
• Frequently Asked Questions
• Conclusion

Setup and Installation

Getting started with Got is refreshingly simple. First, install it:

npm install got

Here's your first request:

import got from 'got';

const response = await got('https://api.github.com/users/octocat');
console.log(response.body);

That's it. No configuration objects, no wrestling with response parsing. Got automatically handles JSON responses, follows redirects sensibly, and gives you helpful error messages when things go wrong.

For TypeScript users (and you should be one), Got has excellent type definitions built-in:

interface User {
  login: string;
  name: string;
  public_repos: number;
}

const user = await got('https://api.github.com/users/octocat').json<User>();
console.log(user.name); // Fully typed!

5 Essential Patterns You'll Use Daily

1. Automatic Retry with Exponential Backoff

APIs fail. Networks hiccup. Got handles this gracefully:

const response = await got('https://api.example.com/flaky-endpoint', {
  retry: {
    limit: 3,
    methods: ['GET', 'POST'],
    statusCodes: [408, 413, 429, 500, 502, 503, 504],
    errorCodes: ['ETIMEDOUT', 'ECONNRESET'],
    backoffLimit: 3000
  }
});

I use this pattern for every production API call. It's saved me countless times when dealing with rate limits or temporary service disruptions. The exponential backoff means you're not hammering a struggling server, which is just good citizenship.

2. Request Cancellation and Timeouts

Nothing's worse than a hanging request. Got makes timeouts granular and sensible:

import got from 'got';

const controller = new AbortController();

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  const response = await got('https://slow-api.example.com', {
    signal: controller.signal,
    timeout: {
      request: 10000,  // Total request timeout
      lookup: 1000,    // DNS lookup
      connect: 2000,   // TCP connection
      secureConnect: 2000,  // TLS handshake
      send: 5000,      // Sending request
      response: 5000   // Waiting for response
    }
  });
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request was cancelled');
  }
}

This granular control has helped me identify exactly where slow requests were bottlenecking. Turns out, our DNS was the problem, not the API.

3. Stream Processing for Large Files

Downloading large files without streaming is a recipe for memory disasters:

import got from 'got';
import { createWriteStream } from 'fs';
import { pipeline } from 'stream/promises';

await pipeline(
  got.stream('https://example.com/large-file.zip'),
  createWriteStream('downloaded-file.zip')
);

// With progress tracking
const downloadStream = got.stream('https://example.com/large-file.zip');

downloadStream.on('downloadProgress', progress => {
  const percent = (progress.percent * 100).toFixed(2);
  console.log(`Downloaded: ${percent}%`);
});

await pipeline(downloadStream, createWriteStream('file.zip'));

I've used this to download multi-gigabyte datasets without breaking a sweat. The progress tracking is perfect for building user-facing download features.

4. Custom Instances with Defaults

Stop repeating yourself. Create configured instances:

import got from 'got';

const api = got.extend({
  prefixUrl: 'https://api.example.com',
  headers: {
    'Authorization': `Bearer ${process.env.API_TOKEN}`,
    'User-Agent': 'MyApp/1.0'
  },
  timeout: {
    request: 10000
  },
  retry: {
    limit: 2
  },
  hooks: {
    beforeRequest: [
      options => {
        console.log(`Requesting: ${options.url}`);
      }
    ]
  }
});

// Now all requests use these defaults
const users = await api('users').json();
const posts = await api('posts').json();

This pattern has cleaned up so much duplicated code in my projects. One instance per API, configured once, used everywhere.

5. Pagination Made Simple

APIs love pagination. Got makes it bearable:

import got from 'got';

const api = got.extend({
  prefixUrl: 'https://api.github.com',
  pagination: {
    transform: (response) => JSON.parse(response.body),
    paginate: ({ response, currentItems }) => {
      const link = response.headers.link;
      if (!link) return false;

      const nextUrl = link.match(/<([^>]+)>;\s*rel="next"/)?.[1];
      if (!nextUrl) return false;

      return { url: new URL(nextUrl) };
    }
  }
});

// Collect all pages automatically
const allRepos = await api.paginate.all('users/sindresorhus/repos');
console.log(`Total repos: ${allRepos.length}`);

Performance Comparison

Here's how Got stacks up against alternatives (average of 1000 requests):

Got strikes a sweet balance. It's not the absolute fastest, but the developer experience and built-in features more than compensate for the minimal overhead. In real-world applications, the retry logic and error handling actually improve overall reliability.

3 Mistakes That'll Bite You

Mistake 1: Not Handling Errors Properly

Got throws detailed errors, but you need to catch them:

// BAD
const data = await got('https://api.example.com').json();

// GOOD
try {
  const data = await got('https://api.example.com').json();
} catch (error) {
  if (error.response) {
    console.log(`Status: ${error.response.statusCode}`);
    console.log(`Body: ${error.response.body}`);
  } else {
    console.log(`Request failed: ${error.message}`);
  }
}

I learned this the hard way when a 404 crashed my entire application.

Mistake 2: Forgetting to Set Timeouts

The default timeout is generous—maybe too generous:

// This could hang forever on a slow network
const response = await got('https://unreliable-api.com');

// Always set reasonable timeouts
const response = await got('https://unreliable-api.com', {
  timeout: { request: 5000 }
});

Mistake 3: Not Reusing Instances

Creating a new Got instance for every request wastes resources:

// BAD - Creates new instance each time
async function getUser(id) {
  return got(`https://api.example.com/users/${id}`).json();
}

// GOOD - Reuse configured instance
const api = got.extend({ prefixUrl: 'https://api.example.com' });

async function getUser(id) {
  return api(`users/${id}`).json();
}

Frequently Asked Questions

Q: Should I use Got or Axios?

Got is more modern, has better TypeScript support, and handles streams natively. Axios has a larger ecosystem and browser support. For Node.js-only projects, I choose Got every time.

Q: Does Got work in the browser?

No, Got is Node.js-only. For universal code, consider ky (from the same author) or axios.

Q: How do I upload files with Got?

Use form-data:

import FormData from 'form-data';
import { createReadStream } from 'fs';

const form = new FormData();
form.append('file', createReadStream('photo.jpg'));

await got.post('https://api.example.com/upload', { body: form });

Q: Can I use Got with proxies?

Yes, Got supports HTTP/HTTPS proxies through agents:

import { HttpsProxyAgent } from 'hpagent';

await got('https://api.example.com', {
  agent: {
    https: new HttpsProxyAgent({ proxy: 'http://proxy.example.com:8080' })
  }
});

Q: Is Got maintained?

Absolutely. Sindre Sorhus actively maintains it, and it's used by thousands of projects.

Conclusion

Got transformed HTTP requests from a chore into something I actually enjoy working with. The automatic retries have saved production systems, the streaming support handles massive files elegantly, and the error messages actually help me fix problems.

Is it perfect? No. The bundle size is larger than bare-bones alternatives, and the learning curve exists if you want to use advanced features. But for 99% of use cases, Got hits the sweet spot between power and simplicity.

Give it a shot on your next project. Your future self—the one who isn't debugging cryptic HTTP errors at 2 AM—will thank you.