A maioria dos aplicativos da web modernos conversam com um servidor o tempo todo. A JavaScript Fetch API é a maneira padrão de fazer isso e está integrada aos navegadores e ao Node.js 18 e posterior, portanto, não há nada para instalar.

O uso básico leva duas linhas, mas muitos tutoriais param por aí e deixam de fora a parte que causa bugs reais: o tratamento de falhas. Testamos os exemplos neste guia em um pequeno servidor local no Node.js 24, e a saída mostrada vem dessa execução. example.com no código representa sua própria API. Se as promessas são novas para você, comece com Promessas JavaScript explicadas.

O que é a API de busca?

Fetch é uma interface baseada em promessas para fazer solicitações HTTP. Ele substituiu o antigo, baseado em retorno de chamada XMLHttpRequest, e muitos projetos agora o utilizam em vez de adicionar uma biblioteca para chamadas simples.

Uma solicitação GET

Fetch faz uma solicitação GET por padrão. Existem duas etapas, e cada uma precisa de await: primeiro chegam os cabeçalhos de resposta e depois você lê o corpo.

const response = await fetch("https://example.com/users/1");
const user = await response.json();

console.log(user);

// { id: 1, name: 'Asha' }

As duas etapas existem porque o corpo pode ser grande e chegar depois dos cabeçalhos. Em um script de navegador, o nível superior await precisa de um módulo, então você normalmente colocará isso dentro de uma função async. Consulte nosso guia JavaScript assíncrono/aguardado.

O objeto Resposta

Antes de ler o corpo, você pode inspecionar a resposta:

console.log(response.status, response.ok, response.headers.get("content-type"));

// 200 true application/json

Um corpo pode ser lido apenas uma vez. Chamar json() uma segunda vez falhou em nosso teste:

await res.json();
await res.json();

// TypeError: Body is unusable: Body has already been read

Se você precisar lê-lo duas vezes, ligue para response.clone() primeiro.

A grande surpresa: um 404 não joga

Esta é a coisa mais importante neste artigo. Solicitamos um usuário que não existe:

const res = await fetch("https://example.com/users/999");
console.log(res.status, res.ok);

// 404 false

Nenhuma exceção foi lançada. No que diz respeito à busca, a solicitação funcionou: o servidor foi alcançado e respondeu. A promessa é rejeitada apenas quando nenhuma resposta utilizável chega, como acontece com uma falha de rede. Portanto, um código como este tem um bug oculto:

try {
  const res = await fetch(url);
  const data = await res.json();   // may be an error payload
  showUser(data);                  // runs anyway for 404 and 500
} catch (error) {
  showError();                     // does not run for 404 or 500
}

Verifique nossa folha de referências de códigos de status HTTP para ver o que cada código significa.

Um ajudante reutilizável

Não repita essa verificação em todos os lugares. Embrulhe uma vez:

async function getJson(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

try {
  await getJson("https://example.com/users/999");
} catch (error) {
  console.log("caught:", error.message);
}

// caught: Request failed with status 404

Agora, erros de HTTP e erros de rede terminam no mesmo catch. Vale a pena ter esta pequena função em todos os projetos. Uma versão real também pode ler uma mensagem de erro do corpo da resposta e manipular uma resposta 204 No Content, que não possui JSON para analisar.

POSTAR dados JSON

Passe um objeto de opções como segundo argumento. Para JSON, você deve fazer duas coisas: converter os dados em uma string e definir o cabeçalho.

const created = await getJson("https://example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ben" }),
});

console.log(created);

// { id: 2, name: 'Ben', type: 'application/json' }

Nosso servidor de teste repetiu o tipo de conteúdo recebido, confirmando a chegada do cabeçalho. Esquecer esse cabeçalho é uma causa comum de erros confusos no servidor, porque muitos frameworks apenas analisam JSON quando ele é declarado. Para fazer upload de um formulário ou arquivos, passe um objeto FormData como corpo e não defina Content-Type, pois o próprio navegador precisa adicionar um valor de limite.

Outros métodos e opções

Escolhendo entre REST e outros estilos de API? Nossa comparação de REST vs GraphQL mostra como a busca se encaixa em cada um.

Cadeias de caracteres de consulta

Não crie strings de consulta juntando texto, pois caracteres especiais irão quebrá-las. URLSearchParams cuida da codificação para você:

const params = new URLSearchParams({ q: "red shoes", page: 2 });
console.log(params.toString());

// q=red+shoes&page=2

await getJson(`https://example.com/search?${params}`);

// { q: 'red shoes', page: '2' }

O servidor recebeu red shoes corretamente, com o espaço restaurado.

Tempo limite e cancelamento

O Fetch esperará muito tempo em um servidor lento, a menos que você informe o contrário. AbortSignal.timeout() define um limite. Nosso endpoint de teste levou dois segundos, contra um limite de 200 milissegundos:

try {
  await fetch("https://example.com/slow", { signal: AbortSignal.timeout(200) });
} catch (error) {
  console.log(error.name);
}

// TimeoutError

Para cancelar manualmente, por exemplo, quando um usuário sai de uma página ou digita um novo termo de pesquisa, use um AbortController:

const controller = new AbortController();
const pending = fetch("https://example.com/slow", { signal: controller.signal });

controller.abort();

try {
  await pending;
} catch (error) {
  console.log(error.name);
}

// AbortError

Para executar várias solicitações de uma vez, use Promise.all, que é muito mais rápido do que aguardá-las uma de cada vez:

const [user, search] = await Promise.all([
  getJson("https://example.com/users/1"),
  getJson("https://example.com/search?q=a&page=1"),
]);

Todo tipo de fracasso

Aqui está a aparência de cada falha em nossa execução, além de como diferenciá-las:

Essa última linha é comum na produção. Um proxy que retorna um 502 geralmente envia uma página de erro HTML. Reproduzimos isso e res.json() lançou um SyntaxError. Marcar response.ok antes de analisar significa que você relata o problema real em vez de um erro de análise confuso.

CORS e credenciais

Em um navegador, uma solicitação de uma origem para outra está sujeita ao CORS, as regras de compartilhamento de recursos entre origens. Se você vir um erro mencionando Access-Control-Allow-Origin, a correção pertence ao servidor, que deve permitir o seu site. No seu JavaScript, a falha aparece apenas como um genérico TypeError, então procure no console do navegador o motivo real. O Node.js não impõe CORS, portanto, uma solicitação que funciona em um script ainda pode falhar no navegador.

Por padrão, os navegadores não enviam cookies em solicitações de origem cruzada. Defina credentials: "include" se precisar deles e certifique-se de que o servidor permita. Nunca coloque chaves de API secretas no JavaScript do navegador, pois qualquer pessoa pode lê-las. Mantenha-os em seu servidor.

Erros comuns

• Não verificando response.ok. As respostas de erro são tratadas como sucesso.
• Esquecer o segundo await. response.json() também retorna uma promessa.
• Esquecer JSON.stringify. Passar um objeto conforme o corpo envia [object Object].
• Definir Content-Type com FormData. Isso quebra os limites, então deixe-o de fora.
• Sem tempo limite. Uma solicitação interrompida pode deixar o controle giratório de uma página em execução indefinidamente.
• Analisando JSON para uma resposta vazia. Um 204 não tem corpo e json() será lançado.

Considerações finais

Buscar é simples quando você se lembra de sua regra principal: uma resposta não é o mesmo que um sucesso. Copie o pequeno auxiliar em seu projeto, adicione um tempo limite e teste seus caminhos de falha. Na próxima etapa, crie uma pequena página que carregue dados de uma API, mostre uma mensagem de erro clara e permita ao usuário cancelar uma pesquisa lenta.

Perguntas frequentes

Continue aprendendo