Tratando Erros com +error.svelte

Em um mundo perfeito, o código nunca falha. No mundo real, APIs ficam indisponíveis, bancos de dados expiram, usuários digitam URLs erradas e sessões expiram no meio de uma requisição. O SvelteKit possui um sistema robusto para lidar com essas situações de forma elegante através dos arquivos +error.svelte.

O que é um Limite de Erro?

Um limite de erro é um componente que captura erros lançados por seus descendentes e renderiza uma UI alternativa em vez de deixar o erro se propagar e travar toda a aplicação. Se uma função de carregamento lança um erro, o SvelteKit para de renderizar aquela rota e procura o +error.svelte mais próximo na hierarquia de rotas para renderizar em seu lugar.

A palavra-chave é mais próximo. O SvelteKit nem sempre recorre a uma página de erro global — ele procura o +error.svelte ancestral mais próximo e renderiza o erro lá, mantendo todos os layouts pai intactos. Um post de blog com falha não derruba o índice do blog. Um widget de painel com falha não elimina a navegação.

Esse confinamento do "raio de impacto" é o que separa uma experiência de erro profissional de uma quebrada. Em vez de uma tela branca que perde o usuário completamente, um erro em uma parte do seu app produz um fallback elegante exatamente naquela parte — o restante da UI continua funcionando.

Os usuários vão encontrar erros. O que importa é se eles têm um caminho claro a seguir quando isso acontece. Um limite de erro bem posicionado com ações de recuperação úteis — uma caixa de busca no 404, um botão de nova tentativa no 500, um link de login no 401 — mantém os usuários engajados. Uma tela em branco os perde.

Criando uma Página de Erro

Seu arquivo +error.svelte recebe detalhes do erro via o estado page:

<!-- src/routes/+error.svelte -->
<script lang="ts">
	import { page } from '$app/state'
</script>

<div class="error-container">
	<h1>{page.status}</h1>
	<p class="message">{page.error?.message}</p>

	<a href="/">Go back home</a>
</div>

<style>
	.error-container {
		text-align: center;
		padding: 4rem 2rem;
	}

	h1 {
		font-size: 6rem;
		margin: 0;
		color: var(--brand);
	}

	.message {
		font-size: 1.25rem;
		color: var(--text-dimmed);
		margin-bottom: 2rem;
	}

	a {
		display: inline-block;
		padding: 0.75rem 1.5rem;
		background: var(--brand);
		color: white;
		text-decoration: none;
		border-radius: 4px;
	}
</style>

Lançando Erros Esperados

Às vezes você sabe que algo está errado. Por exemplo, se um usuário solicita um post de blog que não existe, isso é um erro 404. Você pode acionar isso manualmente usando o helper error:

// src/routes/blog/[slug]/+page.ts
import { error } from '@sveltejs/kit'
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/posts/${params.slug}`)

	if (response.status === 404) {
		// Stop execution and show the error page
		error(404, {
			message: 'Post not found',
			hint: 'The post you are looking for might have been removed.'
		})
	}

	if (!response.ok) {
		error(response.status, 'Failed to load post')
	}

	return {
		post: await response.json()
	}
}

Formato do Objeto de Erro

A função error() aceita:

Um código de status (400, 404, 500, etc.)
Uma string de mensagem OU um objeto com propriedades personalizadas

// Simple message
error(404, 'Not found')

// Object with custom properties
error(403, {
	message: 'Access denied',
	hint: 'You need to be logged in to view this page.',
	code: 'AUTH_REQUIRED'
})

Acessando Detalhes do Erro

No seu +error.svelte, acesse o erro via page.error:

<script lang="ts">
	import { page } from '$app/state'
</script>

<h1>Error {page.status}</h1>
<p>{page.error?.message}</p>

{#if page.error?.hint}
	<p class="hint">{page.error.hint}</p>
{/if}

{#if page.status === 404}
	<div class="suggestions">
		<h2>You might be looking for:</h2>
		<ul>
			<li><a href="/blog">Blog</a></li>
			<li><a href="/docs">Documentation</a></li>
			<li><a href="/">Homepage</a></li>
		</ul>
	</div>
{/if}

Páginas de Erro em Cascata

As páginas de erro se propagam em cascata para cima na hierarquia de rotas. O SvelteKit procura o arquivo +error.svelte mais próximo e renderiza o erro lá, dentro de todos os layouts pai acima dele:

src/routes/
├── +error.svelte              → Global fallback (inside root layout)
├── +layout.svelte
├── blog/
│   ├── +error.svelte          → Blog-specific errors (inside root layout)
│   ├── +layout.svelte
│   └── [slug]/
│       └── +page.ts           → If this throws...

Se src/routes/blog/[slug]/+page.ts lançar um erro:

O SvelteKit verifica src/routes/blog/[slug]/+error.svelte — não encontrado
Verifica src/routes/blog/+error.svelte — encontrado, renderiza este
O +layout.svelte raiz o envolve, então o usuário ainda vê a navegação do site

Isso significa que a página de erro do blog é renderizada dentro do layout raiz. O usuário vê a mensagem de erro, mas ainda tem o cabeçalho, rodapé e navegação do site. Eles não ficam desamparados. Podem ir a outro lugar.

É por isso que o posicionamento importa: um +error.svelte ao lado de uma página profundamente aninhada captura apenas os erros daquela página e é renderizado dentro de toda a UI pai. Um +error.svelte na raiz captura tudo, mas não tem UI pai para envolvê-lo. Escolha o posicionamento com base em quanto contexto você quer preservar quando algo falha.

Isso permite páginas de erro específicas por seção que combinam com a identidade da seção:

<!-- src/routes/blog/+error.svelte -->
<script lang="ts">
	import { page } from '$app/state'
</script>

<div class="blog-error">
	<h1>Oops! {page.status}</h1>
	<p>{page.error?.message}</p>

	<h2>Recent Posts</h2>
	<!-- Keep the user engaged with other content -->
	<a href="/blog">Browse all posts</a>
</div>

Contexto de Layout na Página de Erro

As páginas de erro são renderizadas dentro do layout pai. Isso significa que seu cabeçalho e rodapé ainda aparecem:

Root Layout (+layout.svelte)
├── Header
├── Main
│   └── Error Page (+error.svelte) ← Renders here
└── Footer

Se você quiser que a página de erro substitua a página inteira (sem layout), você precisa redefinir o layout:

src/routes/
├── +layout.svelte
├── +error.svelte      → Uses root layout
└── +error@.svelte     → Resets to NO layout (bare page)

Tipos de Erro Diferentes

404 - Não Encontrado

// Page doesn't exist
error(404, 'Page not found')

// Resource doesn't exist
error(404, {
	message: 'User not found',
	hint: 'This account may have been deleted.'
})

403 - Proibido

error(403, {
	message: 'Access denied',
	hint: "You don't have permission to view this resource."
})

401 - Não Autorizado

// Usually redirect instead, but sometimes error is appropriate
error(401, 'Please log in to continue')

500 - Erro de Servidor

// Don't expose internal details to users
error(500, 'Something went wrong. Please try again later.')

Tratando Erros Inesperados

Quando ocorre um erro não tratado (um bug no seu código), o SvelteKit:

Registra o erro completo no console do servidor
Exibe um erro genérico para o usuário (ocultando detalhes sensíveis)

Você pode personalizar isso em hooks.server.ts:

// src/hooks.server.ts
import type { HandleServerError } from '@sveltejs/kit'

export const handleError: HandleServerError = async ({ error, event, status, message }) => {
	// Log the full error for debugging
	console.error('Unexpected error:', error)

	// Send to error tracking service
	await reportToSentry(error, {
		url: event.url.pathname,
		userId: event.locals.user?.id
	})

	// Return a safe error message for the user
	return {
		message: 'An unexpected error occurred',
		code: 'INTERNAL_ERROR'
	}
}

Projetando Boas Páginas de Erro

Inclua Ações Úteis

<script lang="ts">
	import { page } from '$app/state'

	function goBack() {
		history.back()
	}
</script>

<div class="error-page">
	<h1>{page.status === 404 ? 'Page Not Found' : 'Something Went Wrong'}</h1>
	<p>{page.error?.message}</p>

	<div class="actions">
		<button onclick={goBack}>Go Back</button>
		<a href="/">Home</a>
		<a href="/contact">Report Issue</a>
	</div>
</div>

Conteúdo Específico por Status

<script lang="ts">
	import { page } from '$app/state'

	const errorContent = {
		404: {
			title: 'Page Not Found',
			emoji: '🔍',
			suggestion: "The page you're looking for doesn't exist."
		},
		403: {
			title: 'Access Denied',
			emoji: '🔒',
			suggestion: "You don't have permission to view this page."
		},
		500: {
			title: 'Server Error',
			emoji: '💥',
			suggestion: 'Something went wrong on our end. Please try again.'
		}
	}

	let content = $derived(
		errorContent[page.status] ?? {
			title: 'Error',
			emoji: '⚠️',
			suggestion: page.error?.message
		}
	)
</script>

<div class="error-page">
	<span class="emoji">{content.emoji}</span>
	<h1>{content.title}</h1>
	<p>{content.suggestion}</p>
</div>

Lógica de Repetição

Para erros transitórios, ofereça uma opção de tentar novamente:

<script lang="ts">
	import { invalidateAll } from '$app/navigation'
	import { page } from '$app/state'

	let retrying = $state(false)

	async function retry() {
		retrying = true
		await invalidateAll()
		retrying = false
	}
</script>

{#if page.status >= 500}
	<button onclick={retry} disabled={retrying}>
		{retrying ? 'Retrying...' : 'Try Again'}
	</button>
{/if}

Conclusão

O tratamento de erros no SvelteKit representa um equilíbrio criterioso entre redes de segurança automáticas e controle explícito. Ao fornecer arquivos +error.svelte em pontos estratégicos da sua hierarquia de rotas, você cria limites de erro em cascata que capturam falhas e apresentam alternativas amigáveis ao usuário em vez de telas em branco ou erros genéricos do navegador.

O helper error() transforma falhas de validação e erros de lógica de negócio em respostas de erro estruturadas que fluem naturalmente pela hierarquia de layouts da sua aplicação.

Dominar o tratamento de erros significa compreender a distinção entre erros esperados (lançados com error()) e erros inesperados (capturados pelo handleError). Erros esperados devem fornecer orientações claras ao usuário e caminhos de recuperação, enquanto erros inesperados exigem registro, monitoramento e degradação graciosa.

Ao projetar páginas de erro que mantenham a aparência da sua aplicação, forneçam ações úteis e respeitem a hierarquia de layouts, você constrói aplicações que falham graciosamente e mantêm a confiança do usuário mesmo quando as coisas dão errado.

Pontos Principais

+error.svelte cria páginas de limite de erro que capturam erros em funções de carregamento e componentes de página, renderizando uma UI alternativa em vez de quebrar toda a aplicação
O helper error() sinaliza erros estruturados com códigos de status HTTP e mensagens: error(404, 'Post not found') retorna uma resposta 404 com mensagens amigáveis ao usuário
Páginas de erro cascadeiam a partir do limite mais próximo - o SvelteKit percorre a árvore de rotas em busca do +error.svelte mais próximo, recorrendo ao raiz se nenhum existir
Acesse detalhes do erro via page de $app/state — page.status fornece o código de status HTTP e page.error contém a mensagem de erro e quaisquer propriedades personalizadas que você passou para error()
Páginas de erro são renderizadas dentro dos layouts pai mantendo navegação, cabeçalhos e UI consistente mesmo durante falhas
O hook handleError registra erros inesperados em hooks.server.ts, permitindo monitoramento de erros, sanitização e registro antes que os erros cheguem aos clientes
Projete páginas de erro com ações de recuperação - caixas de busca para erros 404, botões de tentar novamente para erros 500, links de navegação para ajudar os usuários a continuarem sua jornada
Conteúdo específico por status melhora a UX - diferencie entre 404 (não encontrado), 403 (proibido), 500 (erro do servidor) com mensagens e ações apropriadas

Veja Também

Documentação Oficial do SvelteKit - Tratamento de Erros
Helper error() - Lançando erros esperados
Hook handleError - Registrando erros inesperados
page de $app/state — Acessando detalhes de erro, rota e URL em componentes
Códigos de Status HTTP - Significados dos códigos de status padrão
Monitoramento de Erros - Rastreamento e alertas de erros em produção