Tratamento de erros: códigos de estado HTTP
Mapear códigos de estado HTTP para mensagens exibidas ao utilizador, distinguir entre erros de rede e erros do servidor e implementar uma lógica de novas tentativas.
Tratamento de erros: códigos de estado HTTP é uma aula grátis de Frontend Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Frontend Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Frontend Academy inclui 4 aulas no total.
Categorias de códigos de status HTTP
Os códigos de status são agrupados pelo primeiro dígito: 2xx sucesso, 3xx redirecionamento, 4xx erro do cliente (sua responsabilidade), 5xx erro do servidor (responsabilidade do servidor).
Códigos 2xx comuns
200 OK: sucesso com corpo. 201 Criado: recurso criado (geralmente retorna o novo recurso). 204 Sem conteúdo: sucesso sem corpo (DELETE, às vezes PUT).
Códigos 4xx comuns
400 Solicitação inválida: entrada malformada. 401 Não autorizado: autenticação ausente ou inválida. 403 Proibido: autenticado, mas sem permissão. 404 Não encontrado: o recurso não existe. 409 Conflito: conflito de estado (e-mail duplicado). 422 Entidade não processável: a validação falhou.
Códigos 5xx comuns
500 Erro interno do servidor: falha genérica do servidor. 502 Gateway inválido: o serviço upstream falhou. 503 Serviço indisponível: o servidor está sobrecarregado ou fora do ar. 504 Tempo limite do gateway: o serviço upstream não respondeu a tempo.
Mapeando códigos para mensagens ao usuário
Converta os códigos de status em mensagens úteis na interface — nunca mostre “Erro 500” ao usuário.
function userMessage(status) {
if (status === 401) return 'Please sign in to continue.';
if (status === 403) return "You don't have permission for that.";
if (status === 404) return 'Not found.';
if (status === 409) return 'Already exists.';
if (status === 422) return 'Please check the form for errors.';
if (status >= 500) return 'Something went wrong. Try again in a moment.';
return 'Something unexpected happened.';
}Erros de rede vs erros do servidor
Uma chamada fetch que falha (modo offline, falha de DNS, CORS) é diferente de uma resposta de erro do servidor. Erros de rede geram exceções; erros do servidor retornam uma resposta com status >= 400.
try {
const res = await fetch('/api/users');
if (!res.ok) {
// Server replied but with error status
throw new Error(`Server error ${res.status}`);
}
return res.json();
} catch (err) {
if (err instanceof TypeError) {
// Network failure — fetch couldn't reach server
throw new Error('Network error. Check your connection.');
}
throw err;
}Lógica de repetição para erros 5xx e de rede
Erros do servidor e falhas de rede costumam ser temporários. Repita a tentativa usando recuo exponencial.
async function fetchWithRetry(url, options, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
const res = await fetch(url, options);
if (res.ok || (res.status >= 400 && res.status < 500)) return res;
// 5xx — retryable
} catch (err) {
if (attempt === maxRetries - 1) throw err;
}
await new Promise(r => setTimeout(r, 2 ** attempt * 1000)); // 1s, 2s, 4s
}
}Não repita requisições 4xx
Erros 4xx são responsabilidade do cliente — repeti-los não ajudará. Repita apenas erros 5xx e falhas de rede. A exceção é 429 (Muitas solicitações), que geralmente inclui um cabeçalho Retry-After.
Lendo o cabeçalho Retry-After
Os servidores podem incluir Retry-After em respostas 429 e 503 — aguarde essa quantidade de segundos antes de repetir a tentativa.
const res = await fetch('/api/limited');
if (res.status === 429) {
const after = parseInt(res.headers.get('Retry-After') || '5', 10);
await new Promise(r => setTimeout(r, after * 1000));
return fetch('/api/limited');
}Exibindo erros de validação
As respostas 422 normalmente incluem um corpo JSON que lista os erros dos campos. Renderize-os ao lado do campo de entrada correspondente no formulário.
// Server response for 422:
// { errors: { email: 'Already taken', password: 'Too short' } }
if (res.status === 422) {
const { errors } = await res.json();
Object.entries(errors).forEach(([field, msg]) => {
setFieldError(field, msg);
});
}Telemetria: registrando erros em um serviço
Envie erros para Sentry, Datadog ou LogRocket para visualizá-los em produção. Inclua a URL da requisição, o método, o status e um corpo sanitizado (sem segredos).
Oferecendo uma recuperação acionável
Toda interface de erro deve oferecer ao usuário um caminho para continuar: um botão para repetir a tentativa, um link para o suporte ou uma forma de voltar a uma página funcional. Telas de erro sem saída frustram os usuários.
Verificação rápida
Uma API retorna 422 Entidade não processável. O que isso normalmente significa?
Recapitulação: tratamento de erros HTTP
2xx sucesso, 3xx redirecionamento, 4xx erro do cliente, 5xx erro do servidor. Converta os códigos em mensagens claras para o usuário. Diferencie erros de rede (TypeError de fetch) de erros do servidor (res.ok falso). Repita erros 5xx e falhas de rede usando recuo exponencial; nunca repita erros 4xx (exceto 429 com Retry-After). Exiba os erros dos campos em respostas 422. Registre erros em um serviço como o Sentry.
Perguntas Frequentes
A aula “Tratamento de erros: códigos de estado HTTP” é grátis?
Sim — o texto completo de “Tratamento de erros: códigos de estado HTTP” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Frontend Academy, atualize para CoddyKit PRO. O curso de Frontend Academy inclui 4 aulas no total.
O que vou aprender em “Tratamento de erros: códigos de estado HTTP”?
Mapear códigos de estado HTTP para mensagens exibidas ao utilizador, distinguir entre erros de rede e erros do servidor e implementar uma lógica de novas tentativas. Você pratica Frontend Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar Frontend Academy?
Nenhuma experiência prévia é necessária. Frontend Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.
Quanto tempo leva a aula “Tratamento de erros: códigos de estado HTTP”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de Frontend Academy?
Sim. Cada aula de Frontend Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- API Fetch: GET POST PUT DELETE
- Axios: interceptadores e URL base
- Tratamento de erros: códigos de estado HTTP
- SWR e React Query para armazenamento em cache de dados