A API Fetch — Padrões para Requisições HTTP do Mundo Real

fetch() agora está integrado em todos os navegadores modernos e no Node.js 18+. Ele substituiu o XMLHttpRequest e eliminou a necessidade do Axios na maioria dos projetos. Mas o uso padrão que todo tutorial mostra — fetch(url).then(r => r.json()) — ignora o tratamento de erros, não tem timeout e falha em qualquer ambiente de produção real. Este guia cobre os padrões que realmente funcionam.

O Básico — GET e POST

fetch() retorna uma Promise que resolve com um objeto Response. Uma requisição GET é simples:

const response = await fetch('https://api.example.com/products');
const products = await response.json();

Uma requisição POST com corpo JSON precisa de um pouco mais de configuração:

const newProduct = {
  name:     'Wireless Keyboard',
  price:    79.99,
  category: 'electronics'
};

const response = await fetch('https://api.example.com/products', {
  method:  'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${authToken}`
  },
  body: JSON.stringify(newProduct)
});

const created = await response.json();
console.log(`Created product with id: ${created.id}`);

Erro comum: esquecer o Content-Type: application/json em requisições POST. Sem ele, muitos frameworks de servidor não irão fazer o parse do corpo, e você receberá um 400 Bad Request ou um corpo de requisição vazio sem nenhuma mensagem de erro útil.

A Verificação de Erro em Dois Passos — response.ok

Este é o padrão mais importante para internalizar. fetch() só rejeita sua Promise em erros de rede (sem conexão, falha de DNS, bloqueio de CORS). Uma resposta 404, 401 ou 500 ainda resolve a Promise — com response.ok definido como false. Se você não verificar isso, passará silenciosamente respostas de erro para response.json():

// ❌ Broken — 404 and 500 responses appear to succeed
async function getProduct(id) {
  const response = await fetch(`/api/products/${id}`);
  return await response.json(); // parses the error body as if it were data
}

// ✅ Correct — check response.ok before parsing
async function getProduct(id) {
  const response = await fetch(`/api/products/${id}`);

  if (!response.ok) {
    // Try to get the error message from the body if it's JSON
    const errorBody = await response.json().catch(() => null);
    const message   = errorBody?.message ?? `HTTP ${response.status}: ${response.statusText}`;
    throw new Error(message);
  }

  return await response.json();
}

response.ok é true para códigos de status 200–299. Qualquer outra coisa — redirecionamentos 301 (se não seguidos automaticamente), erros 400, erros 500 — define como false. Sempre verifique antes de fazer o parse.

AbortController — Timeouts e Cancelamento

fetch() não tem timeout integrado. Uma requisição pode travar indefinidamente se o servidor parar de responder no meio da transferência. A solução é o AbortController:

async function fetchWithTimeout(url, options = {}, timeoutMs = 10000) {
  const controller = new AbortController();
  const timeoutId  = setTimeout(() => controller.abort(), timeoutMs);

  try {
    const response = await fetch(url, {
      ...options,
      signal: controller.signal
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    return await response.json();
  } catch (err) {
    if (err.name === 'AbortError') {
      throw new Error(`Request timed out after ${timeoutMs}ms`);
    }
    throw err;
  } finally {
    clearTimeout(timeoutId);
  }
}

// Usage
try {
  const data = await fetchWithTimeout('/api/products', {}, 5000);
} catch (err) {
  console.error(err.message); // "Request timed out after 5000ms"
}

AbortController também é útil para cancelar requisições em andamento quando um usuário navega para outra página ou realiza uma nova busca antes que a anterior seja concluída:

let searchController = null;

async function searchProducts(query) {
  // Cancel any previous search request
  if (searchController) {
    searchController.abort();
  }

  searchController = new AbortController();

  try {
    const response = await fetch(
      `/api/products/search?q=${encodeURIComponent(query)}`,
      { signal: searchController.signal }
    );
    return await response.json();
  } catch (err) {
    if (err.name !== 'AbortError') throw err;
    return null; // request was cancelled — that's OK
  }
}

Retry com Backoff Exponencial

Requisições de rede falham de forma transitória — um 503 numa tentativa muitas vezes tem sucesso na próxima. O backoff exponencial é a estratégia padrão: esperar progressivamente mais entre as tentativas para evitar sobrecarregar um servidor já sobrecarregado:

async function fetchWithRetry(url, options = {}, retries = 3, baseDelayMs = 500) {
  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      const response = await fetch(url, options);

      // Don't retry client errors (4xx) — they won't fix themselves
      if (response.status >= 400 && response.status < 500) {
        throw new Error(`Client error ${response.status} — not retrying`);
      }

      if (!response.ok) {
        throw new Error(`Server error ${response.status}`);
      }

      return await response.json();

    } catch (err) {
      const isLastAttempt = attempt === retries;

      if (isLastAttempt || err.message.includes('Client error')) {
        throw err;
      }

      // Exponential backoff with jitter: 500ms, 1000ms, 2000ms + random
      const delay = baseDelayMs * 2 ** (attempt - 1) + Math.random() * 100;
      console.warn(`Attempt ${attempt} failed, retrying in ${Math.round(delay)}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

// Usage
const products = await fetchWithRetry('/api/products', {}, 3, 500);

O jitter é importante: Adicionar Math.random() * 100 ao delay evita o "thundering herd" — onde milhares de clientes fazem retry exatamente no mesmo momento após uma falha do servidor. Pequeno offset aleatório, grande benefício para a confiabilidade.

Um Padrão de Interceptor — Encapsulando o fetch()

O Axios popularizou o conceito de interceptor: um hook que é executado antes de cada requisição e após cada resposta. Você pode construir a mesma coisa como um wrapper fino ao redor do fetch():

// api.js — your project's fetch wrapper
const API_BASE = 'https://api.example.com';

function getAuthToken() {
  return localStorage.getItem('authToken');
}

async function apiFetch(path, options = {}) {
  const url = `${API_BASE}${path}`;

  // Request interceptor — add auth header to every request
  const headers = {
    'Content-Type': 'application/json',
    ...options.headers
  };

  const token = getAuthToken();
  if (token) headers['Authorization'] = `Bearer ${token}`;

  const response = await fetch(url, { ...options, headers });

  // Response interceptor — handle auth expiry globally
  if (response.status === 401) {
    logout(); // token expired — redirect to login
    throw new Error('Session expired');
  }

  if (!response.ok) {
    const body = await response.json().catch(() => ({}));
    throw new Error(body.message ?? `API error ${response.status}`);
  }

  // Return null for 204 No Content
  if (response.status === 204) return null;

  return response.json();
}

// Usage — clean, no repeated boilerplate
const products = await apiFetch('/products');
const created  = await apiFetch('/products', {
  method: 'POST',
  body:   JSON.stringify({ name: 'New Product', price: 29.99 })
});

Este padrão centraliza autenticação, tratamento de erros e configuração de URL base. Toda chamada de API no seu código obtém o mesmo comportamento automaticamente. Quando os requisitos mudam — como adicionar um novo header ou trocar de JWT para cookies de sessão — você atualiza em um único lugar.

Tratando Diferentes Tipos de Resposta

Nem toda API retorna JSON. fetch() tem métodos para todos os tipos de resposta comuns:

// JSON (most common)
const data = await response.json();

// Plain text (CSV, HTML, logs)
const csvText = await response.text();

// Binary data — download a file
const blob       = await response.blob();
const blobUrl    = URL.createObjectURL(blob);
const downloadLink = document.createElement('a');
downloadLink.href     = blobUrl;
downloadLink.download = 'export.csv';
downloadLink.click();
URL.revokeObjectURL(blobUrl); // clean up

// ArrayBuffer — for WebAssembly or typed arrays
const buffer     = await response.arrayBuffer();
const byteArray  = new Uint8Array(buffer);

// Form data (multipart responses)
const formData = await response.formData();

CORS — O Que os Desenvolvedores Precisam Saber

CORS (Cross-Origin Resource Sharing) é aplicado pelo navegador, não pelo servidor. Quando seu frontend em app.example.com busca dados de api.example.com, o navegador envia um header Origin e verifica a resposta para obter permissão. Aqui está o que você controla do lado do cliente:

// credentials: 'include' — send cookies/session tokens cross-origin
// The server must also respond with Access-Control-Allow-Credentials: true
const response = await fetch('https://api.example.com/account', {
  credentials: 'include'
});

// credentials: 'same-origin' — default, only sends credentials to same origin
// credentials: 'omit' — never send credentials (useful for public CDN requests)

// mode: 'no-cors' — fire-and-forget for cross-origin requests
// You get a "opaque" response — no status, no body, no error
await fetch('https://analytics.example.com/event', {
  method: 'POST',
  mode:   'no-cors',
  body:   JSON.stringify({ event: 'page_view' })
});
// Use for analytics pings where you don't need the response

Se você está recebendo erros de CORS, a correção quase sempre está no servidor: o servidor precisa adicionar Access-Control-Allow-Origin nos seus headers de resposta. O guia CORS do MDN é a referência mais completa sobre como configurá-lo.

Ferramentas Úteis

Quando você está depurando respostas fetch, o Formatador JSON torna os payloads de API legíveis e o Validador JSON detecta respostas malformadas. Para codificar parâmetros de query com segurança, o JSON URL Encode resolve. O guia MDN Using Fetch é a melhor referência única para todas as opções do fetch e métodos de resposta.

Conclusão

fetch() é uma base sólida para requisições HTTP em JavaScript, mas os padrões default deixam de fora tudo o que você precisa em produção. Sempre verifique response.ok antes de fazer o parse. Adicione timeouts com AbortController. Construa uma função wrapper fina para lidar com headers de autenticação, normalização de erros e redirecionamentos 401 em um único lugar. Adicione lógica de retry com backoff exponencial para requisições que podem falhar transitoriamente. Esses quatro hábitos são a diferença entre código de demonstração e código de produção.

← All JavaScript articles Browse all categories →