Fetch API em JavaScript: requisições, JSON e erros

Fetch: um cliente HTTP baseado em Promises

A fetch já vem embutida nos navegadores e nas versões modernas do Node. Você passa uma URL, e ela devolve uma Promise que resolve para um objeto Response. No fundo, é essa a API inteira:

fetch("https://jsonplaceholder.typicode.com/todos/1")
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(err => console.error("falhou:", err));

Dois .then em sequência porque existem duas etapas assíncronas: primeiro chegam os cabeçalhos da resposta (é isso que a primeira promise entrega), e só depois o corpo é lido e convertido (response.json() também é uma promise). O corpo só é baixado quando você pede.

O mesmo fluxo com async/await fica parecendo código comum, lido de cima para baixo:

async function loadTodo() {
    const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");
    const data = await response.json();
    console.log(data);
}

loadTodo();

Dois await, dois pontos de suspensão. O mesmo trabalho, só que bem mais fácil de ler de cima pra baixo.

O objeto Response

O que a fetch devolve não é o corpo da resposta — é um objeto Response, que traz os metadados e os métodos para você ler esse corpo em diferentes formatos:

async function inspect() {
    const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");

    console.log(response.status);       // 200
    console.log(response.ok);           // true para 200-299
    console.log(response.headers.get("content-type"));

    const data = await response.json();
    console.log(data.title);
}

inspect();

Você pode ler o corpo da resposta usando .json(), .text(), .blob(), .arrayBuffer() ou .formData(). Cada um desses métodos retorna uma promise. E tem um detalhe importante: o corpo só pode ser lido uma vez — se você chamar .json() duas vezes na mesma resposta, a segunda chamada vai estourar um erro.

A maior pegadinha: erros HTTP não rejeitam a promise

Essa aqui confunde praticamente todo mundo que está começando com o fetch. Uma resposta 404 ou 500 não é uma rejeição. A promise resolve normalmente, só que com response.ok === false. O fetch só rejeita quando a requisição em si não conseguiu completar — falha de DNS, sem conexão de rede ou bloqueio por CORS.

Na prática, isso significa que um fetch ingênuo vai aceitar numa boa uma página de erro e só vai quebrar depois, na hora do .json():

async function buggy() {
    // Esta URL retorna 404, mas fetch resolve mesmo assim.
    const response = await fetch("https://jsonplaceholder.typicode.com/nope/999");
    const data = await response.json();    // pode explodir ou retornar lixo
    console.log(data);
}

buggy();

A solução é verificar response.ok manualmente e lançar um erro quando o servidor retornar um status de erro:

async function loadTodo(id) {
    const response = await fetch(`https://jsonplaceholder.typicode.com/todos/${id}`);

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

    return response.json();
}

loadTodo(1).then(console.log).catch(err => console.error(err.message));

Acostume-se a escrever esse bloco if (!response.ok). Ele merece um lugar em todo wrapper de fetch que você criar.

Fazendo uma requisição POST com fetch

GET é o método padrão. Para qualquer outro verbo HTTP, basta passar um segundo argumento — um objeto de opções:

async function createPost() {
    const response = await fetch("https://jsonplaceholder.typicode.com/posts", {
        method: "POST",
        headers: {
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            title: "hello",
            body: "from fetch",
            userId: 1
        })
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const data = await response.json();
    console.log(data);
}

createPost();

Três coisas que vale a pena destacar:

• method tem como padrão "GET". Defina explicitamente quando for POST, PUT, DELETE ou PATCH.
• body aceita uma string (ou FormData, Blob, etc.) — o fetch não serializa objetos automaticamente para você. O JSON.stringify(...) é responsabilidade sua.
• O header Content-Type diz ao servidor como interpretar o corpo da requisição. Se esquecer, a maioria dos servidores vai tratar o body como texto puro.

Headers, query strings e outras opções do fetch

Os headers podem ser um objeto comum (ou uma instância de Headers). Já a query string você monta na mão, normalmente com URLSearchParams:

async function search(query, token) {
    const params = new URLSearchParams({ q: query, limit: "10" });
    const url = `https://api.example.com/search?${params}`;

    const response = await fetch(url, {
        headers: {
            "Authorization": `Bearer ${token}`,
            "Accept": "application/json"
        }
    });

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

URLSearchParams cuida da codificação pra você — espaços, &, unicode — assim você não acaba com URLs quebradas quando a entrada tem caracteres que precisam ser escapados.

Outras opções que você vai ver em código real: credentials: "include" pra enviar cookies em requisições cross-origin, cache: "no-store" pra ignorar o cache HTTP, e mode: "cors" (que normalmente é o padrão) pra controlar o comportamento de CORS.

Cancelando uma requisição com AbortController

Às vezes você precisa desistir da requisição — o usuário digitou uma nova busca, ou a chamada está demorando demais. É aí que entra o AbortController:

async function loadWithTimeout(url, ms) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), ms);

    try {
        const response = await fetch(url, { signal: controller.signal });
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        return await response.json();
    } finally {
        clearTimeout(timeout);
    }
}

loadWithTimeout("https://jsonplaceholder.typicode.com/todos/1", 3000)
    .then(console.log)
    .catch(err => console.error(err.name, err.message));

controller.abort() faz com que a promise do fetch seja rejeitada com uma DOMException cujo name é "AbortError". Já o bloco finally limpa o timeout para que uma requisição bem-sucedida não deixe um timer pendurado por aí.

Esse padrão — fetch com timeout e limpeza — vale a pena ser encapsulado em um helper para reutilizar em todo lugar.

Um wrapper reutilizável

Juntando tudo, dá pra montar um pequeno helper que cuida do boilerplate de uma vez só:

async function apiRequest(url, options = {}) {
    const response = await fetch(url, {
        headers: { "Content-Type": "application/json", ...options.headers },
        ...options
    });

    if (!response.ok) {
        const text = await response.text();
        throw new Error(`HTTP ${response.status}: ${text || response.statusText}`);
    }

    if (response.status === 204) return null;   // Sem Conteúdo
    return response.json();
}

apiRequest("https://jsonplaceholder.typicode.com/todos/1")
    .then(console.log)
    .catch(err => console.error(err.message));

Um único lugar pra ajustar headers, um único lugar pra tratar erros, um único lugar pra lidar com respostas vazias. Todo app minimamente sério acaba chegando em algo parecido com isso.

A seguir: tratamento de erros em código assíncrono

O fetch é um dos pontos onde erros assíncronos mais aparecem, e a verificação do response.ok é só uma das peças do quebra-cabeça. A próxima página fala sobre tratamento de erros em promises e async/await — pra onde os erros vão, como capturá-los e as armadilhas que deixam eles passarem despercebidos.