tRPC End-to-End Type Safe APIs · Lekcja

Niestandardowe typy błędów

Zdefiniują Państwo niestandardowe typy błędów w backendzie i będą je zgłaszać tak, aby poprawnie docierały do frontendu.

Lekcja 2 z 410 kroki

Niestandardowe typy błędów to bezpłatna lekcja tRPC End-to-End Type Safe APIs na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej tRPC End-to-End Type Safe APIs, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs tRPC End-to-End Type Safe APIs zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

Why Custom Error Types?

In tRPC, we often use TRPCError for handling issues. But sometimes, you need more specific error types.

  • Clarity: Custom errors make your code clearer about what went wrong.
  • Specific Handling: Allows the frontend to react differently to distinct error conditions.
  • Better Debugging: Provides more context than a generic error.

Let's learn how to define and use them!

Basic Custom Error Class

At its simplest, a custom error is a class that extends JavaScript's built-in Error class. This ensures it behaves like a standard error.

It usually takes a message and sets its own name property.

class MyCustomError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'MyCustomError';
  }
}

function main() {
  try {
    throw new MyCustomError('Something specific went wrong!');
  } catch (error) {
    if (error instanceof MyCustomError) {
      console.log(`Caught: ${error.name} - ${error.message}`);
    } else {
      console.log(`Caught generic error: ${error.message}`);
    }
  }
}

main();

tRPC's TRPCError

For tRPC to correctly understand and propagate errors, your custom errors should extend TRPCError from @trpc/server.

TRPCError requires an object with a code (e.g., 'NOT_FOUND', 'BAD_REQUEST') and a message. This code helps the client understand the error type.

Defining a tRPC Custom Error

Here's how you define a custom error for tRPC, ensuring it extends TRPCError and sets a relevant status code.

This example creates a UserNotFoundError. Notice we pass the tRPC code to the super() constructor.

import { TRPCError } from '@trpc/server';

class UserNotFoundError extends TRPCError {
  constructor(userId: string) {
    super({
      code: 'NOT_FOUND',
      message: `User with ID '${userId}' not found.`
    });
    this.name = 'UserNotFoundError';
  }
}

function main() {
  try {
    throw new UserNotFoundError('user-123');
  } catch (error) {
    if (error instanceof TRPCError) {
      console.log(`Error Code: ${error.code}`);
      console.log(`Error Message: ${error.message}`);
    }
  }
}

main();

Throwing Custom Errors (Backend)

Once defined, you can throw your custom error directly within your tRPC procedures (queries or mutations). tRPC will automatically catch it and send it to the client.

This allows your backend logic to signal specific issues clearly.

import { publicProcedure, router } from './trpc'; // Assume trpc setup
import { TRPCError } from '@trpc/server';

class UserNotFoundError extends TRPCError {
  constructor(userId: string) {
    super({ code: 'NOT_FOUND', message: `User ${userId} not found.` });
    this.name = 'UserNotFoundError';
  }
}

const appRouter = router({
  getUser: publicProcedure
    .input(z.string())
    .query(async ({ input: userId }) => {
      // Simulate database lookup
      if (userId === 'nonexistent') {
        throw new UserNotFoundError(userId); // Throw our custom error!
      }
      return { id: userId, name: `User ${userId}` };
    }),
});

// Note: `z` for Zod input validation is assumed here
// The router itself is not runnable without a full server context.

Frontend: Receiving Errors

On the frontend, when a tRPC procedure fails, the client-side tRPC library will throw an instance of TRPCClientError.

This error object contains the code and message from your backend TRPCError, allowing you to identify the specific issue.

Frontend: Identifying Custom Errors

To handle specific custom errors on the client, you can use a try...catch block and inspect the error object.

  • Check error.data.code: This is the most reliable way as it's directly from the TRPCError code.
  • Check error.message: Less reliable, but can be used for specific messages.
  • instanceof (with shared types): If you share the custom error class definition between client and server, you can use instanceof. This is common in monorepos.

Frontend Example: Handling UserNotFoundError

Here's how a React component (or similar frontend logic) might handle our UserNotFoundError using the error.data.code property.

This allows you to display a user-friendly message specific to the error.

import { trpc } from './utils/trpc'; // Assume trpc client setup

function UserProfile({ userId }: { userId: string }) {
  const { data, error, isLoading } = trpc.getUser.useQuery(userId);

  if (isLoading) {
    return '<p>Loading user data...</p>';
  }

  if (error) {
    if (error.data?.code === 'NOT_FOUND') {
      return `<p>User with ID <b>${userId}</b> does not exist.</p>`;
    } else {
      return `<p>An unexpected error occurred: ${error.message}</p>`;
    }
  }

  return `<h1>Welcome, ${data?.name}!</h1>`;
}

function main() {
  // This function simulates component usage.
  // In a real app, trpc.getUser.useQuery would trigger an API call.
  console.log('Simulating UserProfile for existing user...');
  // Assume UserProfile('user-123') would render 'Welcome, User user-123!'

  console.log('Simulating UserProfile for nonexistent user...');
  // Assume UserProfile('nonexistent') would render 'User with ID nonexistent does not exist.'
}

main();

Quick Check

Which of the following are good reasons to define and use custom error types in tRPC, especially when extending TRPCError?

Recap: Custom Error Types

Great job! You've learned how to leverage custom error types in tRPC:

  • Extend TRPCError: For tRPC to correctly propagate your errors.
  • Specify code: Use tRPC's error codes (e.g., 'NOT_FOUND') for standardization.
  • Throw on Backend: Signal specific issues from your procedures.
  • Catch on Frontend: Use error.data.code for precise error handling.

This approach leads to more robust and user-friendly applications by clearly communicating backend issues to the client.

Bezpłatny start

Ucz się tRPC End-to-End Type Safe APIs dzięki korepetycjom AI — za darmo

Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.

Kursy
10
Lekcje
40

Często zadawane pytania

Czy lekcja „Niestandardowe typy błędów” jest bezpłatna?

Tak — pełny tekst „Niestandardowe typy błędów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu tRPC End-to-End Type Safe APIs, przejdź na CoddyKit PRO. Kurs tRPC End-to-End Type Safe APIs zawiera 4 lekcji w sumie.

Co nauczysz się w „Niestandardowe typy błędów”?

Zdefiniują Państwo niestandardowe typy błędów w backendzie i będą je zgłaszać tak, aby poprawnie docierały do frontendu. Ćwiczysz tRPC End-to-End Type Safe APIs z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć tRPC End-to-End Type Safe APIs?

Nie wymagamy żadnego doświadczenia. tRPC End-to-End Type Safe APIs w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Niestandardowe typy błędów”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji tRPC End-to-End Type Safe APIs?

Tak. Każda lekcja tRPC End-to-End Type Safe APIs zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Elegancka obsługa błędów tRPC
  2. Niestandardowe typy błędów
  3. Transformery danych do serializacji
  4. Formatowanie błędów i informacje zwrotne z walidacji pól
← Powrót do tRPC End-to-End Type Safe APIs