Como fazer fetch() lidar com respostas JSON e texto de forma gradual e segura

Em aplicações web modernas, o consumo de APIs assíncronas é rotina, especialmente com fetch(). Contudo, um problema recorrente é lidar com respostas que podem variar entre JSON válido e texto de erro. Essa situação é comum em APIs que retornam erros como strings simples ao invés de objetos JSON estruturados.

---

Problema Concreto: respostas heterogêneas e controle de fluxo

Imagine uma API que, ao retornar sucesso, envia um JSON bem estruturado, mas, ao erro, responde com uma mensagem textual simples. Para o frontend, isso gera uma dificuldade: como consumir essa resposta sem quebrar a aplicação, especialmente se tentarmos fazer res.json() e ela falhar?

O padrão usual de fetch() é tentar fazer res.json(), mas, quando a resposta é texto, essa operação dispara uma exceção, levando o fluxo direto para o catch, que muitas vezes não consegue tratar adequadamente esse texto, causando erros difíceis de debugar. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

---

Diagnóstico: por que o res.json() falha?

O método res.json() tenta interpretar a corpo da resposta como JSON. Se a resposta for um texto simples — por exemplo, uma mensagem de erro — esse método lança uma exceção, que precisa ser capturada para evitar falhas na aplicação. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois.

O problema é que, na maioria das implementações, o fetch() não consegue distinguir antecipadamente se a resposta será JSON ou texto, especialmente quando a API é inconsistente ou não padroniza seus retornos de erro. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

Abordagem recomendada: leitura inicial como texto e parsing condicional

A estratégia mais prática é ler a resposta como texto inicialmente, e depois tentar fazer o parse para JSON. Assim, é possível detectar se a resposta é válida ou apenas uma mensagem de erro.

Por exemplo, ao invés de fazer res.json() de imediato, faz-se res.text(), e então tenta-se interpretar o conteúdo. Caso o parse de JSON falhar, podemos tratar o erro como uma mensagem de texto. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte.

---

Exemplo técnico: implementação prática

fetch(apiUrl)
  .then(res => res.text())
  .then(body => {
    try {
      const jsonData = JSON.parse(body). // resposta é JSON válido, devolve os dados
      return jsonData. } catch (e) {
      // não foi possível parsear, trata como mensagem de erro
      throw new Error(body). }
  })
  .then(data => {
    // manipula dados JSON
    console.log('Dados recebidos:', data). })
  .catch(error => {
    // aqui trata tanto erro de parsing quanto mensagens de erro
    console.error('Erro ou mensagem de erro:', error.message). }). 

Essa abordagem evita que a aplicação quebre ao receber respostas não padronizadas, além de manter a lógica de controle mais clara. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. A decisão fica mais saudável quando o time consegue medir o impacto depois. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. A decisão fica mais saudável quando o time consegue medir o impacto depois. A decisão fica mais saudável quando o time consegue medir o impacto depois. A decisão fica mais saudável quando o time consegue medir o impacto depois.

Trade-offs e pontos de atenção

• Performance: ler a resposta como texto e fazer parse adicionalmente pode impactar um pouco a performance, mas é uma troca aceitável na maioria dos casos, considerando a robustez.
• Padronização de API: ideal seria incentivar a API a responder sempre com JSON, mesmo em erros, usando estruturas predefinidas. Mas, enquanto isso não ocorre, essa abordagem é uma solução prática.
• Controle de erros: ao fazer parse manual, você consegue distinguir claramente entre erro de conexão, erro na resposta, ou mensagem de erro específica.

Falhas comuns ao aplicar essa técnica

• Não tratar respostas que retornam vazias ou com conteúdo inesperado.
• Assumir que toda resposta não JSON é erro, sem verificar seu conteúdo.
• Esquecer de validar o conteúdo antes de usar os dados, o que pode gerar bugs.

Passos práticos para implementar

1. Sempre ler a resposta como texto antes de qualquer parse.
2. Implementar um bloco try/catch ao fazer JSON.parse().
3. Tratar a mensagem de erro ou resposta inválida de forma diferenciada.
4. Documentar esse comportamento na sua equipe, para evitar surpresas.

---

Conclusão

Lidar com respostas heterogêneas em fetch() exige uma abordagem mais controlada e consciente. Prefira sempre ler como texto primeiro, e só depois tentar interpretar como JSON. Assim, você evita que erros de parsing prejudiquem seu fluxo de trabalho, além de ganhar maior controle sobre o que sua aplicação consome. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. Sem esse critério, a solução pode parecer simples no começo e cara no suporte.

No seu time, essa estratégia ajuda até na depuração de problemas de API, pois você consegue diferenciar facilmente entre uma resposta válida e uma mensagem de erro inesperada. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

O que vocês têm feito em casos assim? Já tiveram que lidar com APIs que retornam respostas inconsistentes desse tipo? A decisão fica mais saudável quando o time consegue medir o impacto depois. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta.