Como as Funções de Load Param Cedo

Funções de load falham por todo tipo de razão comum: um usuário está procurando um registro que não existe, a sessão dele expirou, ele não tem permissão para visualizar a página, ou uma API dependente está temporariamente fora do ar. Em cada caso, continuar executando a função de load e retornar dados incompletos causaria mais problemas do que resolveria. Isso pode resultar em um componente quebrado, um erro de runtime críptico, ou pior, servir conteúdo protegido silenciosamente.

O SvelteKit oferece duas funções para lidar com essas situações de forma limpa: error() para renderizar uma página de erro, e redirect() para enviar o usuário para outro lugar. Ambas são importadas de @sveltejs/kit e funcionam da mesma forma — você as chama e elas imediatamente interrompem a função de load lançando internamente. Você não precisa escrever throw você mesmo.

Há também uma terceira categoria que vale conhecer: erros que você não antecipou de forma alguma — um timeout de rede, uma falha ao parsear JSON, uma desreferência nula. O SvelteKit captura esses também e os encaminha através de um hook separado chamado handleError. O usuário vê uma página de erro genérica; os detalhes internos vão para o seu sistema de logging.

A coisa mais importante a entender antes de usar qualquer uma dessas ferramentas é que redirect() e error() funcionam lançando exceções. Qualquer try/catch que os envolva irá acidentalmente engolir o sinal antes que o SvelteKit o veja. Esse único erro (envolver um redirect em um try/catch) é como os guards de rota param de funcionar silenciosamente em produção. Este artigo cobre os três caminhos, na ordem em que você tem mais probabilidade de precisar deles.

Quando uma Função de Load Não Consegue Retornar Dados

Imagine uma página de dashboard. A função de load busca os dados do usuário autenticado. Três coisas podem acontecer quando uma requisição chega. O usuário está autenticado e os dados carregam corretamente. O usuário não está autenticado, e a resposta correta é redirecioná-lo para uma página de login. O usuário está autenticado, mas a API de dados retorna um 500, e a resposta correta é uma página de erro explicando que algo falhou.

Cada um desses resultados precisa de uma instrução diferente para o SvelteKit. Retornar os dados é o caminho de sucesso. Mas para os caminhos de falha, simplesmente retornar um objeto vazio ou null não funciona. O componente de página receberia dados incompletos, tentaria renderizá-los e produziria uma página quebrada ou um erro de runtime que o SvelteKit capturaria como um erro inesperado em vez de um controlado.

No SvelteKit temos duas ferramentas para falha controlada: error() e redirect(), ambas importadas de @sveltejs/kit. Elas não são funções utilitárias que retornam valores para você então lançar. São funções que lançam internamente. Você as chama diretamente, sem throw. Quando sua execução chega aos internos do SvelteKit, o lançamento termina a função de load e transfere o controle para o handler de framework apropriado.

Há também uma terceira categoria: erros que você não pretendia lançar — um timeout de rede, falha ao parsear JSON, uma desreferência nula, etc. Esses são erros inesperados, e o SvelteKit os encaminha através de um mecanismo diferente chamado handleError em hooks.server.ts. Erros inesperados também renderizam uma página de erro, mas as informações apresentadas ao usuário são deliberadamente mínimas, e os detalhes vão para o seu sistema de logging em vez disso.

Os Quatro Resultados

Toda execução de função de load termina de uma das quatro formas. Vê-las juntas antes de mergulhar nos detalhes torna o restante do artigo mais fácil de navegar.

Os quatro caminhos são mutuamente exclusivos. Sua responsabilidade é escolher o caminho certo para cada condição e não interceptar acidentalmente um redirect ou error lançado, que é a falha silenciosa com a qual este artigo está mais preocupado.

Erros Esperados com error()

Um erro esperado é uma condição que sua função de load antecipa e sinaliza explicitamente. Um 404 porque um slug não corresponde a nenhum registro. Um 403 porque o usuário não tem a permissão necessária. Um 503 porque uma dependência está fora do ar e você quer comunicar isso claramente. Esses são erros que você escolhe lançar.

A função error() recebe dois argumentos:

um código de status HTTP
uma mensagem.

import { error } from '@sveltejs/kit'
// error(status: number, message: string | { message: string; [key: string]: any })

error(404, 'Not found')

Os códigos de status mais usados em funções de load:

Código	Nome	Quando usar
`400`	Bad Request	Parâmetros de query ou de rota estão malformados ou inválidos.
`401`	Unauthorized	O usuário não está autenticado (sem sessão, token expirado).
`403`	Forbidden	O usuário está autenticado mas não tem permissão para este recurso.
`404`	Not Found	O registro ou página solicitado não existe.
`410`	Gone	O recurso existia mas foi permanentemente excluído. Prefira ao 404 quando a remoção é intencional e permanente.
`429`	Too Many Requests	O usuário ou cliente excedeu um limite de taxa.
`500`	Internal Server Error	Uma dependência falhou de forma inesperada.
`503`	Service Unavailable	Um serviço upstream necessário está temporariamente fora do ar.

A mensagem pode ser uma string ou um objeto com uma propriedade message. O SvelteKit lança um HttpError internamente e termina a função de load.

// src/routes/blog/[slug]/+page.server.ts

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'

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

	if (response.status === 404) {
		// Signal to SvelteKit that this is an expected, understood condition.
		// The string 'Post not found' will be available in +error.svelte
		// via page.error.message.
		error(404, 'Post not found')
	}

	if (!response.ok) {
		// A non-404 failure is still an expected category here.
		// The status code is passed through so the error page can
		// display or log it appropriately.
		error(response.status, 'Failed to load post')
	}

	const post = await response.json()
	return { post }
}

Após error() ser chamada, nada abaixo dela na função de load é executado. Não há valor de retorno. O SvelteKit intercepta o HttpError lançado e começa a encaminhá-lo para o arquivo +error.svelte mais próximo na hierarquia de rotas.

A mensagem que você passa para error() é intencionalmente voltada para o usuário. Mantenha-a clara e honesta, mas não verbosa. É o que sua página de erro exibirá. Não é uma entrada de log. Não coloque stack traces, nomes de serviços internos ou mensagens de erro de banco de dados na mensagem de error(). Esses pertencem aos logs do servidor, não ao navegador.

A forma de objeto da mensagem é útil quando você quer anexar informações estruturadas adicionais ao erro e lê-las no componente de erro:

// src/routes/admin/reports/[reportId]/+page.server.ts

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ params, locals, fetch }) => {
	if (!locals.user) {
		// A 401 with a structured message object.
		// The error component can read message.code to decide how to render.
		error(401, { message: 'Authentication required', code: 'UNAUTHENTICATED' })
	}

	const response = await fetch(`/api/reports/${params.reportId}`)

	if (response.status === 403) {
		error(403, { message: 'You do not have permission to view this report', code: 'FORBIDDEN' })
	}

	if (response.status === 404) {
		error(404, { message: `Report ${params.reportId} does not exist`, code: 'NOT_FOUND' })
	}

	if (!response.ok) {
		error(500, { message: 'Failed to load report data', code: 'SERVER_ERROR' })
	}

	const report = await response.json()
	return { report }
}

O campo code no objeto de mensagem não é uma convenção do SvelteKit. É um campo personalizado que sua aplicação define. O SvelteKit passa o objeto de mensagem inteiro para page.error, então qualquer formato que você der a ele estará disponível no componente de erro. Use isso de forma consistente em toda a sua aplicação para que as páginas de erro possam renderizar mensagens contextualmente apropriadas.

Como o SvelteKit Encaminha para +error.svelte

Quando error() é lançado de uma função de load, o SvelteKit sobe a hierarquia de rotas procurando pelo arquivo +error.svelte mais próximo. A busca começa no mesmo nível que a função de load que lançou e avança em direção à raiz.

Route that throws: src/routes/blog/[slug]/+page.server.ts

SvelteKit looks for +error.svelte in this order:

  1. src/routes/blog/[slug]/+error.svelte     (most specific, checked first)
  2. src/routes/blog/+error.svelte            (blog section level)
  3. src/routes/+error.svelte                 (root level, catches everything)

O primeiro arquivo +error.svelte encontrado nesta travessia é o que é renderizado. Se nenhum existir em nenhum lugar da hierarquia, o SvelteKit cai de volta para sua página de erro embutida.

Essa hierarquia é intencional. Um 404 em um post de blog não precisa ter a mesma aparência que um 404 na página de pagamento. Ao colocar arquivos +error.svelte em diferentes níveis, você pode dar às seções da sua aplicação sua própria apresentação de erro, ainda tendo um fallback na raiz.

O componente +error.svelte recebe informações de erro através da store page do módulo $app/state. O campo page.status contém o código de status HTTP. O campo page.error contém o valor da mensagem passado para error().

<!-- src/routes/+error.svelte -->
<!-- Root-level error page. Handles all unmatched errors. -->

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

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

	<p class="error-message">
		{page.error?.message ?? 'An unexpected error occurred.'}
	</p>

	{#if page.status === 404}
		<p>The page you are looking for does not exist or has been moved.</p>
	{:else if page.status === 403}
		<p>You do not have permission to access this resource.</p>
	{:else if page.status >= 500}
		<p>Something went wrong on our end. Please try again in a moment.</p>
	{/if}

	<nav class="error-nav">
		<a href="/">Return to home</a>
	</nav>
</div>

<!-- src/routes/blog/+error.svelte -->
<!-- Blog-section error page. Only handles errors thrown from blog routes. -->
<!-- Falls through to +error.svelte at root level if not present here. -->

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

<div class="blog-error">
	<h1>
		{#if page.status === 404}
			Article Not Found
		{:else}
			Something Went Wrong
		{/if}
	</h1>

	<p>{page.error?.message}</p>

	<div class="blog-error-actions">
		<a href="/blog">Browse all articles</a>
		<a href="/">Return to home</a>
	</div>
</div>

Um detalhe importante de layout: o arquivo +error.svelte é renderizado dentro do layout mais próximo que também tem seu próprio +error.svelte definido nele ou acima. Ele não é renderizado de forma isolada. Isso significa que a navegação, fontes e estilos globais do seu layout raiz ainda estão presentes quando a página de erro renderiza, dando a você uma experiência de usuário coerente sem duplicar a estrutura de layout em cada componente de erro.

Redirecionamentos com redirect()

A função redirect() de @sveltejs/kit termina uma função de load e instrui o SvelteKit a enviar uma resposta de redirecionamento para o navegador. Assim como error(), ela funciona lançando internamente.

A função redirect() recebe dois argumentos:

um código de status HTTP — deve estar no intervalo 300–308
uma URL de destino — uma string de caminho ou URL completa

import { redirect } from '@sveltejs/kit'
// redirect(status: 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308, location: string | URL)

redirect(303, '/login')
redirect(301, 'https://example.com/new-url')

Nada após redirect() é executado. A função de load termina no momento em que o redirect é lançado.

O primeiro argumento é o código de status HTTP. Para redirecionamentos em funções de load, o intervalo válido é 300 a 308. A escolha do código de status carrega significado semântico do qual navegadores, mecanismos de busca e caches HTTP dependem. Escolher o errado pode causar redirecionamentos em cache obsoletos, comportamento quebrado do botão voltar, ou mudanças de método em submissões de formulário.

Os códigos mais úteis em funções de load do SvelteKit são 303 e 307.

O status 303 significa "see other" e instrui o cliente a fazer uma requisição GET para o novo local, independentemente do método usado na requisição original.

O status 307 significa "temporary redirect" e preserva o método HTTP, o que significa que um POST para uma URL redirecionada fará POST para o novo local em vez de GET.

Para o caso comum de redirecionar um usuário após autenticação (enviar um visitante não autenticado para a página de login), 303 é quase sempre correto. O usuário chegou via GET. Ele deve ser redirecionado para outro GET. O status 308 é o equivalente permanente do 307, apropriado para conteúdo que foi movido para uma URL canônica para sempre e deve ser atualizado nos índices de mecanismos de busca.

Código	Nome	Método	Duração	Quando usar
`301`	Moved Permanently	GET apenas	Permanente	A URL mudou para sempre. Navegadores e mecanismos de busca fazem cache disso — a URL original nunca deve ser usada novamente.
`302`	Found	GET apenas (na prática)	Temporário	Amplamente usado mas ambíguo. Alguns clientes antigos preservam o método original; a maioria não. Evite em favor de 303 ou 307.
`303`	See Other	Sempre GET	Temporário	Escolha padrão para redirects de autenticação. Envia usuários não autenticados para o login. Sempre resulta em GET independente do método original.
`307`	Temporary Redirect	Preserva o método	Temporário	Use ao redirecionar um POST para outra URL que também deve receber um POST.
`308`	Permanent Redirect	Preserva o método	Permanente	Migrações de URL canônica para endpoints que aceitam métodos não-GET.

Para o dia a dia prático de guards de rota em funções de load, escolha 303. É inequívoco, seguro para navegadores e tem a semântica correta para redirects de autenticação.

A Armadilha do try/catch

Agora entramos na seção mais importante do artigo. Discutimos um erro que parece razoável, porque seu resultado não produz um erro de runtime ou aviso, e silenciosamente desativa completamente o seu guard de rota em produção.

Como sabemos, error() e redirect() funcionam lançando exceções, qualquer bloco try/catch que os envolva capturará o valor lançado e impedirá o SvelteKit de vê-lo. Portanto redirect() ou error() nunca chegam ao framework. A função de load continua executando (ou termina) como se nada tivesse acontecido.

Aqui está como isso parece no contexto de um guard de rota:

// Wrong: the try/catch swallows the redirect thrown by redirect().
// If the user is unauthenticated, redirect() is called, throws internally,
// and the catch block catches it. The load function returns undefined.
// SvelteKit receives no redirect instruction. The page loads anyway.

export const load: PageServerLoad = async ({ locals, fetch }) => {
	try {
		if (!locals.user) {
			redirect(303, '/login')
		}

		const response = await fetch(`/api/user/dashboard`)
		const data = await response.json()
		return { dashboard: data }
	} catch (e) {
		// This catches the redirect thrown by redirect().
		// The developer intends this to catch fetch errors.
		// The result is that unauthenticated users see the dashboard.
		console.error('Load failed:', e)
		error(500, 'Failed to load dashboard')
	}
}

A correção é reestruturar o código para que redirect() e error() sejam chamados fora de qualquer try/catch, ou relançá-los se um try/catch for genuinamente necessário para outro tratamento de erro:

// Correct: redirect() is called before the try/catch block.
// If the user is unauthenticated, redirect() throws and terminates
// the load function. The try/catch below never runs.

export const load: PageServerLoad = async ({ locals, fetch }) => {
	if (!locals.user) {
		redirect(303, '/login')
	}

	try {
		const response = await fetch(`/api/user/dashboard`)

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

		const data = await response.json()
		return { dashboard: data }
	} catch (e) {
		// This try/catch now only wraps the fetch and JSON parse.
		// redirect() and error() above it are not caught here.
		// The catch block handles genuine unexpected failures like network errors.
		console.error('Unexpected load error:', e)
		error(500, 'An unexpected error occurred')
	}
}

Type guard isRedirect

Se por algum motivo você precisar chamar redirect() dentro de um try/catch, você precisa relançar o valor do redirect após detectá-lo com o type guard isRedirect de @sveltejs/kit. Este é um padrão mais propenso a erros, mas é importante conhecê-lo porque você pode encontrá-lo em código existente:

import { redirect, error, isRedirect } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ locals, fetch }) => {
	try {
		if (!locals.user) {
			redirect(303, '/login')
		}

		const response = await fetch(`/api/user/dashboard`)
		return { dashboard: await response.json() }
	} catch (e) {
		// Re-throw redirect and error instances so SvelteKit can handle them.
		// Only catch genuine unexpected errors here.
		if (isRedirect(e)) throw e

		console.error('Unexpected error:', e)
		error(500, 'Something went wrong')
	}
}

Type guard isHttpError

O type guard isHttpError serve ao mesmo propósito para instâncias de error(). Se você está capturando todos os erros em uma função de load e quer deixar as chamadas esperadas de error() passarem, relance-os junto com os redirects:

import { redirect, error, isRedirect, isHttpError } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ params, locals, fetch }) => {
	try {
		if (!locals.user) {
			redirect(303, '/login')
		}

		const response = await fetch(`/api/posts/${params.slug}`)

		if (response.status === 404) {
			error(404, 'Post not found')
		}

		return { post: await response.json() }
	} catch (e) {
		if (isRedirect(e) || isHttpError(e)) throw e

		console.error('Unexpected error:', e)
		error(500, 'Failed to load post')
	}
}

Boas Práticas

A solução mais limpa na maioria dos casos é reestruturar o código para que verificações de guard e lançamentos deliberados de erro aconteçam antes do try/catch. O try/catch deve envolver apenas as linhas específicas de código que podem lançar erros inesperados, como fetch e response.json(). Dessa forma você evita o risco de engolir acidentalmente um redirect ou erro esperado, e sua intenção fica mais clara para leitores futuros.

O padrão de relançamento existe para situações onde reestruturar não é prático, mas requer disciplina: todo bloco catch que pode interceptar um redirect ou error deve relançá-los explicitamente. Se você esquecer de relançar mesmo um, corre o risco de quebrar silenciosamente seus guards de rota e o tratamento de erros de uma forma que só aparece em produção.

A regra a memorizar: nunca coloque redirect() ou error() dentro de um try/catch a menos que você relance instâncias de redirect e error explicitamente.

Erros Inesperados

Um erro inesperado é qualquer erro que sua função de load não sinalizou explicitamente com error(). Um await que falha em um fetch que lança um erro de rede. Eles podem ser: falha ao parsear JSON, desreferência nula porque uma resposta de API tinha um formato diferente do esperado, new Error(...) lançado de uma função utilitária, etc. Esses são erros que você não pretendia lançar, mas que ainda podem acontecer no mundo real. Eles não são esperados, mas também não são impossíveis. São a categoria "ops" de erros.

Quando um erro inesperado ocorre, o SvelteKit o trata invocando o hook handleError em src/hooks.server.ts, passando o objeto de erro, o evento de requisição, um código de status e uma mensagem. O hook é responsável por gerar qualquer ID de erro que precise (por exemplo, via crypto.randomUUID()). Após isso, o SvelteKit renderiza o +error.svelte mais próximo com um código de status 500 e uma mensagem genérica e não específica.

Essa mensagem genérica é intencional. Erros inesperados podem incluir informações internas sensíveis como caminhos de arquivo, queries de banco de dados, nomes de serviços, ou até chaves de API. Expor esses detalhes no navegador representa riscos de segurança e privacidade. Por padrão, o SvelteKit usa { message: 'Internal Error' } para erros inesperados, garantindo que nenhuma informação sensível seja revelada.

O hook handleError é onde você envia as informações reais do erro para algum lugar útil, tipicamente um serviço de logging ou rastreamento de erros:

// src/hooks.server.ts

import type { HandleServerError } from '@sveltejs/kit'

// Note: the export name is 'handleError', not 'handleServerError'.
// 'HandleServerError' is the type; 'handleError' is what SvelteKit looks for.
export const handleError: HandleServerError = async ({ error, event, status, message }) => {
	// 'error' is the raw thrown value. May be an Error instance or anything else.
	// 'event' is the RequestEvent, giving you the URL, headers, and locals.
	// 'status' is the HTTP status code SvelteKit has assigned (usually 500).
	// 'message' is what SvelteKit will show the user ('Internal Error' by default).

	const errorId = crypto.randomUUID()

	// In production, send this to your error tracking service.
	// In development, logging to the console is sufficient.
	console.error({
		errorId,
		status,
		message: error instanceof Error ? error.message : String(error),
		stack: error instanceof Error ? error.stack : undefined,
		url: event.url.pathname,
		method: event.request.method
	})

	// The return value from handleError becomes page.error in +error.svelte.
	// Return something safe that is useful enough for debugging without
	// exposing internal implementation details.
	return {
		message: 'An unexpected error occurred.',
		errorId
	}
}

O valor de retorno de handleError substitui o { message: 'Internal Error' } padrão como o valor de page.error. Ao retornar um errorId, a página de erro pode mostrar aos usuários um número de referência que eles podem fornecer ao contatar o suporte, permitindo que você consulte os detalhes completos no seu sistema de logging sem nunca expor esses detalhes diretamente no navegador.

A distinção entre erros esperados e inesperados importa para a experiência do usuário.

Erros esperados devem ser claros e acionáveis. Um 404 deve dizer ao usuário que o conteúdo não foi encontrado e oferecer um caminho a seguir.
Erros inesperados devem ser honestos sobre a falha enquanto permanecem vagos sobre os internos. O hook handleError torna essa separação possível.

Exemplo Prático: Um Guard de Rota Admin

Uma seção admin é o cenário mais limpo para ver redirect(), error() e a hierarquia de roteamento de erros funcionando juntos no mesmo codebase. Cada conceito deste artigo aparece de forma concreta e testável.

O exemplo modela três caminhos de requisição distintos, cada um produzindo um resultado diferente:

Caminho da requisição	Quem	O que acontece
Sem cookie `sid`	Visitante anônimo	`redirect(303, '/login?returnTo=...')` — enviado para o login, URL de retorno preservada
Cookie `sid` com `role: user`	Autenticado, papel incorreto	`error(403, ...)` — `+error.svelte` admin renderiza com a mensagem 403
Cookie `sid` com `role: admin`	Autenticado, papel correto	Load é bem-sucedido, página renderiza

O exemplo é completamente autocontido. O store de sessão e os dados de usuário são hardcoded — nenhum banco de dados ou serviço externo necessário.

Duas contas de teste estão disponíveis assim que você configurar a página de login:

Valor do cookie (`sid`)	Usuário	Papel
`session-admin-123`	Alice Admin	`admin` — pode acessar `/admin`
`session-user-456`	Bob User	`user` — cai no guard do 403

A estrutura completa de arquivos:

src/
  app.d.ts                          ← augment App.Locals
  hooks.server.ts                   ← populate locals from cookie
  routes/
    +layout.server.ts               ← validate session, expose user to all pages
    +layout.svelte                  ← global layout
    +page.svelte                    ← home page
    login/
      +page.server.ts               ← fake login that sets the sid cookie
      +page.svelte                  ← set / clear the sid cookie
    admin/
      +layout.server.ts             ← auth + authz guard
      +layout.svelte                ← admin shell nav
      +error.svelte                 ← section-specific error page
      +page.svelte                  ← admin dashboard index
      users/
        +page.server.ts             ← fetch paginated users
        +page.svelte                ← render user list
    api/
      session/
        validate/
          +server.ts                ← fake session store
      admin/
        users/
          +server.ts                ← fake user data

Passo 1 — Tipar a sessão em App.Locals

Antes de escrever qualquer função de load, diga ao TypeScript qual formato locals.user tem. Sem isso, todo acesso a locals.user em uma função de load de servidor ou hook é um any implícito.

// src/app.d.ts
declare global {
	namespace App {
		interface Locals {
			user: { id: string; name: string; role: string } | null
		}
	}
}
export {}

Esta única declaração torna locals.user totalmente tipado em todo lugar — hooks, loads de layout, loads de página. Ajuste os campos para corresponder ao que sua API de sessão real retorna.

Etapa 2 — Preencher locals uma vez por requisição em hooks.server.ts

O hook handle em hooks.server.ts é executado antes de cada requisição ser resolvida. É o lugar certo para validar o cookie de sessão e anexar o usuário a event.locals — não dentro de um load de layout.

O motivo está diretamente relacionado à armadilha do try/catch. Se a validação de sessão vivesse dentro de um load de layout envolvido em try/catch para tratamento de erros de fetch, uma chamada descuidada a redirect() ou error() poderia ser silenciada. Executá-la em handle, antes de qualquer função de load ser executada, significa que o usuário validado está disponível em locals no momento em que qualquer função de load o lê. A função de load pode então chamar redirect() ou error() de forma limpa, sem nenhum try/catch por perto.

// src/hooks.server.ts

import type { Handle } from '@sveltejs/kit'

export const handle: Handle = async ({ event, resolve }) => {
	// Skip validation for the session endpoint itself to prevent
	// infinite recursion — event.fetch re-enters this hook.
	if (event.url.pathname === '/api/session/validate') {
		return resolve(event)
	}

	const sessionId = event.cookies.get('sid')

	if (sessionId) {
		const response = await event.fetch('/api/session/validate', {
			method: 'POST',
			headers: { 'Content-Type': 'application/json' },
			body: JSON.stringify({ sessionId })
		})

		if (response.ok) {
			const { user } = await response.json()
			event.locals.user = user
		}
	}

	return resolve(event)
}

Se o cookie estiver ausente ou inválido, event.locals.user nunca é definido. Como App.Locals o declara como { ... } | null, o TypeScript vai exigir que cada função de load trate o caso null.

Etapa 3 — Expor o usuário para páginas públicas no layout raiz

O load do layout raiz é executado para cada rota na aplicação. Ele busca a sessão uma segunda vez — desta vez para popular data.user para os componentes no +layout.svelte raiz. Observe que ele não chama redirect() ou error() aqui, porque a maioria das rotas é pública. Visitantes não autenticados devem poder acessar a página inicial sem serem redirecionados.

// src/routes/+layout.server.ts

import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = async ({ cookies, fetch }) => {
	const sessionId = cookies.get('sid')

	if (!sessionId) {
		return { user: null }
	}

	const response = await fetch('/api/session/validate', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({ sessionId })
	})

	if (!response.ok) {
		return { user: null }
	}

	const { user } = await response.json()
	return { user }
}

Retornar { user: null } é o padrão correto para uma rota pública que não exige autenticação. As chamadas de redirect e error pertencem aos loads que realmente precisam restringir o acesso.

Etapa 4 — O guard do layout admin: onde redirect() e error() aparecem juntos

Este é o arquivo central do exemplo. O +layout.server.ts do admin é onde os dois caminhos de falha deste artigo se encontram em uma única função de load — redirect() para usuários não autenticados, error() para usuários autenticados sem a função necessária.

// src/routes/admin/+layout.server.ts

import type { LayoutServerLoad } from './$types'
import { redirect, error } from '@sveltejs/kit'

export const load: LayoutServerLoad = async ({ locals, url }) => {
	// Authentication check — no session means no business being here.
	// redirect(303) sends the user to login and preserves the current URL
	// as a returnTo param so they land back here after signing in.
	if (!locals.user) {
		redirect(303, `/login?returnTo=${encodeURIComponent(url.pathname)}`)
	}

	// Authorization check — the user IS authenticated, but lacks the role.
	// This is NOT a redirect to login. Their session is valid.
	// Sending them to login would imply the session is broken, which is wrong.
	// error(403) is the accurate signal: authenticated, not permitted.
	if (locals.user.role !== 'admin') {
		error(403, 'You do not have permission to access the admin section.')
	}

	// Both checks passed. Return the user for child layouts and pages to use.
	return { adminUser: locals.user }
}

Observe o que não está aqui: nenhum try/catch. As chamadas redirect() e error() estão no nível superior da função de load, não envolvidas em nada que possa interceptar os throws. Este é exatamente o padrão descrito na seção da armadilha do try/catch — verificações de guard primeiro, operações arriscadas (se houver) depois, em um try/catch separado que não envolve os guards.

Como este é um load de layout, o SvelteKit o executa antes de processar qualquer load de página sob /admin. Se o guard falhar, o load da página nunca é executado. Quando os arquivos +page.server.ts sob /admin forem executados, locals.user tem garantia de existir e ter a função admin.

Etapa 5 — Um load de página admin que depende do guard

Os loads de página sob /admin podem pular a re-verificação de autenticação e autorização. O guard do layout já foi executado. Eles só precisam tratar as falhas específicas de busca de dados que suas próprias chamadas fetch podem produzir.

// src/routes/admin/users/+page.server.ts

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ url, fetch }) => {
	const page = Number(url.searchParams.get('page') ?? '1')
	const perPage = 25

	const response = await fetch(`/api/admin/users?page=${page}&perPage=${perPage}`)

	// error() here is a controlled failure for a fetch problem.
	// It is not inside a try/catch — it sits at the top level of the load.
	if (!response.ok) {
		error(response.status, 'Failed to load user list')
	}

	const { users, total } = await response.json()

	return {
		users,
		pagination: {
			page,
			perPage,
			total,
			totalPages: Math.ceil(total / perPage)
		}
	}
}

Etapa 6 — O +error.svelte específico do admin

Colocar um +error.svelte dentro do diretório admin/ dá à seção admin sua própria página de erro. Quando error(403, ...) é lançado pelo guard do layout admin, o SvelteKit percorre a hierarquia de rotas e encontra este arquivo antes de chegar ao +error.svelte no nível raiz.

<!-- src/routes/admin/+error.svelte -->

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

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

	{#if page.status === 403}
		<p>If you believe you should have access to this section, contact a superadmin.</p>
	{/if}

	<a href="/admin" class="admin-error-back">Return to admin dashboard</a>
</div>

page.status e page.error.message contêm exatamente o que foi passado para error() no guard do layout: 403 e 'You do not have permission to access the admin section.'. O componente de erro os lê diretamente — sem props, sem fetch adicional.

Este arquivo também renderiza dentro do layout admin, portanto o shell de navegação permanece visível quando ocorre um 403. Um usuário autenticado que chega à página proibida ainda vê o frame da aplicação, não uma página em branco. Se você quiser que o erro seja renderizado fora do layout admin — por exemplo, para evitar que uma navegação admin parcialmente renderizada confunda o usuário — remova este arquivo e deixe o erro chegar até src/routes/+error.svelte.

Os arquivos de suporte

Os arquivos restantes são scaffolding que permite exercitar o guard em um navegador sem um banco de dados real.

O componente de layout admin renderiza o shell de navegação e o conteúdo da página filha:

<!-- src/routes/admin/+layout.svelte -->

<script lang="ts">
	import type { LayoutProps } from './$types'

	let { data, children }: LayoutProps = $props()
</script>

<div class="admin-shell">
	<nav class="admin-nav">
		<span class="admin-badge">Admin</span>
		<span class="admin-user">{data.adminUser.name}</span>
		<ul class="admin-links">
			<li><a href="/admin">Dashboard</a></li>
			<li><a href="/admin/users">Users</a></li>
			<li><a href="/admin/reports">Reports</a></li>
			<li><a href="/admin/settings">Settings</a></li>
		</ul>
	</nav>

	<main class="admin-content">
		{@render children()}
	</main>
</div>

data.adminUser está disponível aqui porque o guard do layout retornou { adminUser: locals.user }. Se o guard tivesse redirecionado ou lançado uma exceção, este componente nunca seria renderizado.

As páginas de dashboard e usuários do admin exibem os dados retornados por suas respectivas funções de load:

<!-- src/routes/admin/+page.svelte -->

<script lang="ts">
	import type { PageProps } from './$types'

	let { data }: PageProps = $props()
</script>

<div class="admin-dashboard">
	<h1>Admin Dashboard</h1>
	<p>Welcome, {data.adminUser.name}.</p>

	<nav class="admin-quick-links">
		<a href="/admin/users">Manage Users</a>
	</nav>
</div>

<!-- src/routes/admin/users/+page.svelte -->

<script lang="ts">
	import type { PageProps } from './$types'

	let { data }: PageProps = $props()
</script>

<div class="admin-users">
	<h1>Users</h1>
	<p>{data.pagination.total} total</p>

	<table>
		<thead>
			<tr>
				<th>ID</th>
				<th>Name</th>
				<th>Email</th>
				<th>Role</th>
			</tr>
		</thead>
		<tbody>
			{#each data.users as user (user.id)}
				<tr>
					<td>{user.id}</td>
					<td>{user.name}</td>
					<td>{user.email}</td>
					<td>{user.role}</td>
				</tr>
			{/each}
		</tbody>
	</table>

	<div class="admin-pagination">
		{#if data.pagination.page > 1}
			<a href="/admin/users?page={data.pagination.page - 1}">← Previous</a>
		{/if}
		<span>Page {data.pagination.page} of {data.pagination.totalPages}</span>
		{#if data.pagination.page < data.pagination.totalPages}
			<a href="/admin/users?page={data.pagination.page + 1}">Next →</a>
		{/if}
	</div>
</div>

A página de login define o cookie sid diretamente para simular autenticação. Ela lê o parâmetro de consulta returnTo para que o usuário seja levado de volta à página que estava tentando acessar. Após uma ação de login bem-sucedida, redirect(303, returnTo) o envia para lá. Após o logout, redirect(303, '/') o traz de volta à página inicial.

<!-- src/routes/login/+page.svelte -->

<script lang="ts">
	// Two hardcoded session IDs map to the fake session store in
	// src/routes/api/session/validate/+server.ts
	const sessions = [
		{ label: 'Alice Admin (role: admin)', value: 'session-admin-123' },
		{ label: 'Bob User (role: user)', value: 'session-user-456' }
	]
</script>

<div class="login-demo">
	<h1>Demo Login</h1>
	<p>Pick an account. This sets the <code>sid</code> cookie directly — no real auth.</p>

	{#each sessions as session (session.value)}
		<form method="POST" action="/login?/login">
			<input type="hidden" name="sid" value={session.value} />
			<input
				type="hidden"
				name="returnTo"
				value={new URLSearchParams(globalThis?.location?.search ?? '').get('returnTo') ?? '/admin'}
			/>
			<button type="submit">{session.label}</button>
		</form>
	{/each}

	<form method="POST" action="/login?/logout">
		<button type="submit">Clear cookie (log out)</button>
	</form>
</div>

// src/routes/login/+page.server.ts

import type { Actions } from './$types'
import { redirect } from '@sveltejs/kit'

export const actions: Actions = {
	login: async ({ request, cookies }) => {
		const data = await request.formData()
		const sid = data.get('sid') as string
		const returnTo = (data.get('returnTo') as string) || '/admin'

		cookies.set('sid', sid, {
			path: '/',
			httpOnly: true,
			sameSite: 'lax',
			maxAge: 60 * 60 * 24 // 1 day
		})

		redirect(303, returnTo)
	},

	logout: async ({ cookies }) => {
		cookies.delete('sid', { path: '/' })
		redirect(303, '/')
	}
}

A API de sessão falsa mapeia os dois IDs de sessão codificados para objetos de usuário. Em uma aplicação real, isso consultaria um banco de dados ou cache:

// src/routes/api/session/validate/+server.ts

import { json } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

const sessions: Record<string, { id: string; name: string; role: string }> = {
	'session-admin-123': { id: '1', name: 'Alice Admin', role: 'admin' },
	'session-user-456': { id: '2', name: 'Bob User', role: 'user' }
}

export const POST: RequestHandler = async ({ request }) => {
	const { sessionId } = await request.json()
	const user = sessions[sessionId as string] ?? null

	if (!user) {
		return json({ user: null }, { status: 401 })
	}

	return json({ user })
}

A API falsa de usuários admin retorna uma fatia paginada de usuários codificados:

// src/routes/api/admin/users/+server.ts

import { json } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

const FAKE_USERS = [
	{ id: '1', name: 'Alice Admin', email: 'alice@example.com', role: 'admin' },
	{ id: '2', name: 'Bob User', email: 'bob@example.com', role: 'user' },
	{ id: '3', name: 'Carol Editor', email: 'carol@example.com', role: 'editor' },
	{ id: '4', name: 'Dave Viewer', email: 'dave@example.com', role: 'user' },
	{ id: '5', name: 'Eve Moderator', email: 'eve@example.com', role: 'moderator' }
]

export const GET: RequestHandler = async ({ url }) => {
	const page = Number(url.searchParams.get('page') ?? '1')
	const perPage = Number(url.searchParams.get('perPage') ?? '25')
	const start = (page - 1) * perPage
	const users = FAKE_USERS.slice(start, start + perPage)

	return json({ users, total: FAKE_USERS.length })
}

Erros Comuns e Anti-Padrões

Envolver redirect() em try/catch sem relançar

Este é o erro central do artigo. Vale a pena repetir porque a falha é silenciosa.

// Wrong: redirect() is caught by the catch block.
// The load function does not redirect. The page loads as if the
// guard was never there.
export const load: PageServerLoad = async ({ locals }) => {
	try {
		if (!locals.user) {
			redirect(303, '/login')
		}
		const data = await someRiskyOperation()
		return { data }
	} catch (e) {
		return { data: null }
	}
}

// Correct: redirect() is outside the try/catch,
// or re-thrown if it must appear inside one.
export const load: PageServerLoad = async ({ locals }) => {
	if (!locals.user) {
		redirect(303, '/login')
	}

	try {
		const data = await someRiskyOperation()
		return { data }
	} catch (e) {
		return { data: null }
	}
}

Retornar null ou dados vazios em vez de chamar error()

// Avoid: returning null or partial data when a resource is missing.
// The page component receives null and likely throws a runtime error,
// which becomes an unexpected 500 instead of a clean 404.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/posts/${params.slug}`)

	if (!response.ok) {
		return { post: null }
	}

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

// Preferred: throw a structured error that SvelteKit can route
// to the appropriate +error.svelte file.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/posts/${params.slug}`)

	if (response.status === 404) {
		error(404, 'Post not found')
	}

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

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

Retornar null para um recurso ausente coloca o ônus do estado "não encontrado" em cada componente que usa os dados. Cada componente deve verificar defensivamente se é null antes de renderizar. Se algum componente não fizer essa verificação, o erro será um enigmático "Cannot read properties of null" em vez de uma página 404 clara. Usar error() centraliza o tratamento e produz uma experiência de usuário muito melhor.

Usar redirect() para falhas de autorização

// Avoid: redirecting to login when the user IS authenticated but lacks permission.
// Redirecting to login implies the session is invalid, which is incorrect.
// The user will log in and be redirected back to the same forbidden page.
export const load: PageServerLoad = async ({ locals }) => {
	if (locals.user?.role !== 'admin') {
		redirect(303, '/login')
	}
	// ...
}

// Preferred: use error(403) for authorization failures.
// The user is authenticated. Their session is valid. They simply
// lack the required permission. A 403 communicates that accurately.
export const load: PageServerLoad = async ({ locals }) => {
	if (!locals.user) {
		redirect(303, '/login')
	}

	if (locals.user.role !== 'admin') {
		error(403, 'You do not have permission to access this resource.')
	}
	// ...
}

A distinção entre autenticação (quem você é) e autorização (o que você tem permissão para fazer) mapeia diretamente para a escolha entre redirect() e error(). Autenticação ausente exige um redirecionamento para o login. Autorização insuficiente exige um erro 403. Confundi-las gera confusão nos usuários e torna a aplicação mais difícil de depurar.

Expor detalhes internos de erro através de error()

// Wrong: passing internal details into error() where they reach the browser.
// Database errors, file paths, and internal service names are security concerns.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/posts/${params.slug}`)

	if (!response.ok) {
		const body = await response.json()
		// body.internalError might contain 'PostgreSQL: relation "posts" does not exist at line 1'
		error(500, body.internalError)
	}
	// ...
}

// Correct: pass user-safe messages to error(). Log the internal details
// server-side through handleError or direct logging.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/posts/${params.slug}`)

	if (!response.ok) {
		// Log internally if needed through your logging service.
		// Show the user only what helps them understand what happened.
		error(500, 'Failed to load post data. Please try again.')
	}
	// ...
}

Considerações de Performance e Escalabilidade

Os caminhos de erro e redirecionamento no SvelteKit não são gratuitos do ponto de vista de performance, mas geralmente também não são um gargalo. Alguns padrões merecem consideração à medida que sua aplicação escala.

Guards de rota em loads de layout são executados para cada requisição a cada rota naquela seção. Uma verificação de autenticação no nível raiz que faz uma requisição de rede para validar uma sessão adiciona essa latência a cada carregamento de página. A função handle em hooks.server.ts é um lugar melhor para validação de sessão porque é executada uma vez por requisição e popula locals com o usuário validado, que os loads de layout podem ler sem fazer sua própria requisição de rede. O exemplo do layout admin acima usa locals.user em vez de chamar a API de sessão diretamente, exatamente por esse motivo.

O componente +error.svelte é renderizado usando o mesmo pipeline de renderização server-side das páginas normais. Se sua página de erro fizer suas próprias buscas de dados, essas buscas serão executadas a cada erro. Mantenha as páginas de erro simples e autocontidas. Elas devem renderizar a partir de page.status e page.error sem fazer chamadas de API adicionais.

Para aplicações de alto tráfego com muitos guards de rota, considere se sua lógica de autorização pertence a hooks.server.ts em vez de estar espalhada por múltiplas funções de load de layout. Centralizar a verificação em uma única função handle significa que ela é executada uma vez, popula locals, e cada função de load lê de locals sem uma ida e volta de rede. O load de layout ainda chama error() ou redirect() com base no que encontra em locals, mas a validação de sessão cara acontece apenas uma vez.

Próximos Passos

Agora que você viu todos os principais formatos de função de load — server, universal, página, layout — e seus caminhos de erro e redirecionamento, chegou o momento certo de examinar de perto a camada TypeScript. Os $types gerados fazem mais do que apenas tipar o argumento da função load; eles rastreiam a forma completa dos dados em layouts mesclados, fornecem params tipados e detectam incompatibilidades entre o que uma função de load retorna e o que um componente espera. O próximo artigo, TypeScript e $types em Funções de Load, aborda o sistema de tipos completo em torno do carregamento de dados no SvelteKit.

Veja Também

Documentação de error() do SvelteKit — referência oficial para erros esperados e inesperados, incluindo a lista completa de códigos de status suportados
Documentação de redirect() do SvelteKit — referência oficial para redirect(), incluindo intervalos válidos de códigos de status
Documentação de Hooks do SvelteKit — abrange handleError e o hook handle usado para popular locals com dados de sessão