Response helpers (json, error) in Svelte - Deep Dive

Overview - Response helpers (json, error)

What is it?

Response helpers in Svelte are special functions that make it easy to send back data or errors from server routes. The json helper formats your data as JSON with the right headers. The error helper creates an error response with a status code and message. These helpers simplify how your server talks to the browser or client.

Why it matters

Without response helpers, you would have to manually set headers and format responses every time, which is slow and error-prone. Response helpers save time and prevent bugs by handling common response tasks automatically. This makes your app more reliable and easier to maintain.

Where it fits

You should know basic SvelteKit routing and how server endpoints work before learning response helpers. After this, you can learn about advanced error handling, data loading, and API design in SvelteKit.

Mental Model

Core Idea

Response helpers are like ready-made envelopes that package your data or errors neatly so the client understands them instantly.

Think of it like...

Imagine sending a letter: the json helper is like putting your message in a clear, labeled envelope that says 'This is JSON data,' while the error helper is like sending a letter marked 'Important: Error' with a clear reason why it failed.

┌───────────────┐      ┌───────────────┐
│ Server Route  │─────▶│ json(data)    │
│               │      │ - sets JSON   │
│               │      │   headers     │
│               │      │ - sends data  │
│               │      └───────────────┘
│               │
│               │      ┌───────────────┐
│               │─────▶│ error(status,  │
│               │      │ message)      │
│               │      │ - sets status │
│               │      │ - sends error │
└───────────────┘      └───────────────┘

Build-Up - 6 Steps

1

Foundation

What are response helpers

Concept: Introduce the basic idea of response helpers in SvelteKit.

In SvelteKit, server routes handle requests and send responses. Response helpers are functions you use inside these routes to send data or errors easily. The two main helpers are json() and error(). json() sends JSON data with correct headers. error() sends an error response with a status code and message.

Result

You understand that response helpers simplify sending data or errors from server routes.

Knowing that helpers exist prevents you from writing repetitive code for every response.

2

Foundation

Using json helper to send data

Concept: Learn how to use the json helper to send JSON responses.

Inside a server route, you can return json({ key: 'value' }) to send JSON data. This automatically sets the Content-Type header to application/json and stringifies your object. For example: import { json } from '@sveltejs/kit'; export function GET() { return json({ message: 'Hello world' }); } This sends a JSON response with {"message":"Hello world"}.

Result

The client receives a JSON response with correct headers and data.

Understanding json() saves you from manually setting headers and stringifying data.

3

Intermediate

Using error helper to send errors

🤔Before reading on: do you think error() only sends a message or also sets HTTP status codes? Commit to your answer.

Concept: Learn how error helper creates error responses with status codes.

The error helper lets you send an error response with a status code and message. For example: import { error } from '@sveltejs/kit'; export function GET() { throw error(404, 'Not found'); } This sends a 404 status with the message 'Not found'. The client knows the request failed and why.

Result

The client receives an HTTP error status and message, enabling proper error handling.

Knowing error() sets status codes helps you handle failures clearly and consistently.

4

Intermediate

Combining json and error in routes

🤔Before reading on: do you think you can use json() and error() in the same route depending on conditions? Commit to your answer.

Concept: Use json and error helpers conditionally to handle success and failure.

In a route, you often want to send data if all is good, or an error if something goes wrong. For example: import { json, error } from '@sveltejs/kit'; export function GET({ params }) { if (params.id === '1') { return json({ id: 1, name: 'Alice' }); } else { throw error(404, 'User not found'); } } This sends JSON for a valid id or an error for invalid ids.

Result

Your route handles both success and error cases cleanly using helpers.

Understanding conditional use of helpers leads to robust API design.

5

Advanced

Customizing json responses with headers

🤔Before reading on: do you think json() lets you add custom headers beyond Content-Type? Commit to your answer.

Concept: Learn how to add extra headers to json responses for more control.

json() accepts a second argument where you can add headers or status. For example: import { json } from '@sveltejs/kit'; return json({ message: 'Hello' }, { status: 201, headers: { 'X-Custom': 'value' } }); This sends a 201 Created status and a custom header along with JSON data.

Result

You can customize response status and headers easily with json().

Knowing how to customize responses helps meet API requirements and improve client communication.

6

Expert

How error helper integrates with SvelteKit error handling

🤔Before reading on: do you think throwing error() is the same as returning it? Commit to your answer.

Concept: Understand that error() is meant to be thrown and how SvelteKit processes it.

The error helper creates an Error object with status and message. You must throw it, not return it. SvelteKit catches thrown errors and shows error pages or sends error responses. For example: import { error } from '@sveltejs/kit'; throw error(500, 'Server failure'); If you return error(), it won't work as expected because SvelteKit expects thrown errors to trigger error handling.

Result

You correctly throw error() to trigger SvelteKit's error handling system.

Understanding the throw mechanism prevents silent failures and ensures proper error responses.

Under the Hood

The json helper creates a Response object with the body set to JSON.stringify(data) and headers including Content-Type: application/json. The error helper creates a special Error object with status and message properties. When thrown, SvelteKit's internal router catches this error and converts it into an HTTP response with the given status and message. This mechanism separates normal data responses from error flows cleanly.

Why designed this way?

SvelteKit designed these helpers to reduce boilerplate and enforce consistent response formats. Using helpers avoids mistakes like missing headers or incorrect status codes. Throwing errors instead of returning them fits JavaScript's native error handling, making the flow intuitive and compatible with existing try/catch patterns.

┌───────────────┐
│ Server Route  │
│  (your code)  │
└──────┬────────┘
       │
       │ calls
       ▼
┌───────────────┐          ┌───────────────┐
│ json(data)    │          │ error(status,  │
│ - stringify   │          │ message)      │
│ - set headers │          │ - create Error│
└──────┬────────┘          └──────┬────────┘
       │                          │
       ▼                          ▼
┌─────────────────────────────────────────────┐
│ SvelteKit runtime catches thrown errors      │
│ and sends HTTP responses with status & body │
└─────────────────────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does returning error() from a route send an error response? Commit yes or no.

Common Belief: Returning error() from a route sends an error response to the client.

Reality: You must throw error(), not return it. Returning error() sends it as normal data, not an error response.

Why it matters: Returning error() causes the client to receive unexpected data instead of an error status, breaking error handling.

Quick: Does json() automatically set status code 200 always? Commit yes or no.

Common Belief: json() always sends a 200 OK status code and cannot be changed.

Reality: json() accepts an options object where you can set any status code you want, like 201 or 400.

Why it matters: Assuming json() always sends 200 limits your ability to communicate different response states properly.

Quick: Is it necessary to manually set Content-Type header when using json()? Commit yes or no.

Common Belief: You must manually set Content-Type: application/json header when sending JSON responses.

Reality: json() automatically sets Content-Type to application/json for you.

Why it matters: Manually setting headers wastes time and risks mistakes; json() handles it reliably.

Quick: Can you use error() helper outside of server routes? Commit yes or no.

Common Belief: error() can be used anywhere in Svelte components or client code to handle errors.

Reality: error() is designed for server routes only; using it elsewhere won't trigger proper error responses.

Why it matters: Misusing error() outside server routes leads to confusing bugs and improper error handling.

Expert Zone

1

Throwing error() integrates with SvelteKit's error page system, allowing custom error UI based on status codes.

2

json() can be combined with Response headers and status to implement caching, content negotiation, or security policies.

3

The error helper creates an Error subclass with status, enabling middleware or hooks to inspect and modify error responses.

When NOT to use

Avoid using json() or error() in client-side code or non-SvelteKit environments. For complex APIs, consider full-featured frameworks or libraries that handle serialization, validation, and error formatting more extensively.

Production Patterns

In production, developers use json() for all API responses to ensure consistent JSON format and headers. error() is thrown for all failure cases, enabling centralized error handling and custom error pages. Headers like caching or CORS are added via json() options or hooks for performance and security.

Connections

HTTP status codes

Response helpers use HTTP status codes to communicate success or failure.

Understanding HTTP status codes helps you use error() correctly to signal different error types.

JavaScript Error handling

error() creates and throws Error objects, linking to JavaScript's try/catch mechanism.

Knowing JavaScript error handling clarifies why error() must be thrown, not returned.

REST API design

Response helpers simplify sending standardized JSON responses and errors in REST APIs.

Mastering response helpers improves your ability to build clean, maintainable APIs.

Common Pitfalls

#1 Returning error() instead of throwing it

Wrong approach:

export function GET() {
return error(404, 'Not found');
}

Correct approach:

export function GET() {
throw error(404, 'Not found');
}

Root cause:

Misunderstanding that error() creates an Error object meant to be thrown, not returned.

#2 Manually setting Content-Type header with json()

Wrong approach:

return new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } });

Correct approach:

return json(data);

Root cause:

Not knowing json() automatically sets headers and stringifies data.

#3 Using error() in client-side code

Wrong approach:

import { error } from '@sveltejs/kit';
error(500, 'Client error');

Correct approach:

// Use client-side error handling patterns instead, like throwing or setting state.

Root cause:

Confusing server-side helpers with client-side error handling.

Key Takeaways

Response helpers json() and error() simplify sending JSON data and error responses in SvelteKit server routes.

json() automatically sets the correct headers and stringifies data, saving you from manual work.

error() creates an Error object with status and message that you must throw to trigger SvelteKit's error handling.

Using these helpers correctly leads to cleaner, more reliable server code and better client communication.

Misusing these helpers, like returning error() or using them client-side, causes bugs and broken responses.

Practice

1. What is the main purpose of the json() helper in SvelteKit server endpoints?

easy

A. To parse incoming JSON requests

B. To throw an HTTP error with a message

C. To send a JSON response back to the client

D. To redirect the user to another page

Solution

1. Step 1: Understand the role of json()

   The json() helper formats data as a JSON response for the client.

2. Step 2: Differentiate from other helpers

   Unlike error(), which throws HTTP errors, json() sends data successfully.

3. Final Answer:

   To send a JSON response back to the client -> Option C

4. Quick Check:

   json() sends JSON data [OK]

Hint: json() sends data; error() throws errors [OK]

Common Mistakes:

• Confusing json() with error()
• Thinking json() parses requests
• Assuming json() redirects

2. Which of the following is the correct way to return a JSON response with a status code 200 in a SvelteKit endpoint?

easy

A. return json({ message: 'Success' }, 200);

B. return error(200, { message: 'Success' });

C. return new Response({ message: 'Success' }, 200);

D. return json({ message: 'Success' }, { status: 200 });

Solution

1. Step 1: Check json() syntax

   The json() helper takes data as first argument and an options object with status as second.

2. Step 2: Validate options object usage

   return json({ message: 'Success' }, { status: 200 }); correctly uses { status: 200 } as the second argument.

3. Final Answer:

   return json({ message: 'Success' }, { status: 200 }); -> Option D

4. Quick Check:

   json(data, { status }) syntax [OK]

Hint: json() needs options object for status [OK]

Common Mistakes:

• Passing status as a separate argument without object
• Using error() to send success responses
• Using Response constructor incorrectly

3. Consider this SvelteKit endpoint code:

import { json, error } from '@sveltejs/kit';

export function GET() {
  const data = { user: 'Alice' };
  if (!data.user) {
    throw error(404, 'User not found');
  }
  return json(data);
}

What will be the HTTP status code and response if data.user is missing?

medium

A. Status 200 with empty JSON object

B. Status 404 with message 'User not found'

C. Status 500 with server error

D. Status 200 with user data

Solution

1. Step 1: Analyze the condition

   If data.user is missing (falsy), the code throws error(404, 'User not found').

2. Step 2: Understand error() behavior

   The error() helper throws an HTTP error with the given status and message.

3. Final Answer:

   Status 404 with message 'User not found' -> Option B

4. Quick Check:

   Missing user triggers error(404) [OK]

Hint: error() throws HTTP errors with status and message [OK]

Common Mistakes:

• Assuming json() runs even if error is thrown
• Thinking error() returns JSON data
• Confusing status codes for errors

4. Identify the error in this SvelteKit endpoint code snippet:

import { json, error } from '@sveltejs/kit';

export function POST() {
  const data = { success: true };
  return error(200, 'All good');
}

medium

A. Using error() with status 200 is incorrect

B. Missing return type annotation

C. POST function must be async

D. json() should be used instead of error() to send success

Solution

1. Step 1: Check status code validity

   The error() helper requires status codes 400-599. Using 200 triggers "Non-error status code 200".

2. Step 2: Correct helper for success

   For success (status 200), use json() instead of error().

3. Final Answer:

   Using error() with status 200 is incorrect -> Option A

4. Quick Check:

   Use json() for success, error() for errors [OK]

Hint: error() is for errors, not success responses [OK]

Common Mistakes:

• Using error() with 200 status
• Not returning json() for success
• Assuming error() can send normal data

5. You want to create a SvelteKit endpoint that returns a JSON list of items but throws a 400 error if the list is empty. Which code snippet correctly implements this behavior?

hard

A. export function GET() {
const items = [];
if (items.length === 0) {
throw error(400, 'No items found');
}
return json(items);
}

B. export function GET() {
const items = [];
if (!items) {
return error(400, 'No items found');
}
return json(items);
}

C. export function GET() {
const items = [];
if (items.length === 0) {
return json({ error: 'No items found' }, { status: 400 });
}
return json(items);
}

D. export function GET() {
const items = [];
if (items.length === 0) {
throw json({ error: 'No items found' }, { status: 400 });
}
return json(items);
}

Solution

1. Step 1: Check error throwing for empty list

   export function GET() { const items = []; if (items.length === 0) { throw error(400, 'No items found'); } return json(items); } correctly throws error(400, 'No items found') when the list is empty.

2. Step 2: Validate response for non-empty list

   It returns json(items) properly when items exist.

3. Final Answer:

   export function GET() { const items = []; if (items.length === 0) { throw error(400, 'No items found'); } return json(items); } -> Option A

4. Quick Check:

   Throw error() for HTTP errors, json() for data [OK]

Hint: Throw error() for bad status, json() for good data [OK]

Common Mistakes:

• Returning error() instead of throwing it
• Using json() with error status instead of throwing error()
• Throwing json() which is invalid