Course contentsShow
← TypeScript
Lesson 1294 of 1,79630. Type-Safe APIsFree lesson

Safe Parsing with .safeParse

Use .safeParse() to validate without throwing, returning success or error objects for graceful handling.

Safe Parsing with .safeParse

You'll learn how to validate data without crashing your application by using Zod's .safeParse() method, which returns a result object instead of throwing errors.

The Problem with Throwing Errors

When you use Zod's .parse() method, it throws an error if validation fails. This forces you to wrap every validation in a try-catch block, which can make your code verbose and error-prone. If you forget the try-catch, your entire application could crash on invalid data.

What .safeParse() Does

The .safeParse() method validates data without throwing. Instead, it returns an object that tells you whether validation succeeded or failed:

  • Success case: { success: true, data: T } — the parsed and validated data
  • Error case: { success: false, error: ZodError } — detailed error information

This pattern lets you handle validation failures gracefully with simple conditional logic.

Basic Usage Pattern

import { z } from 'zod';

const UserSchema = z.object({
  name: z.string(),
  age: z.number()
});

const input = { name: "Alice", age: "not a number" };

const result = UserSchema.safeParse(input);

if (result.success) {
  // TypeScript knows result.data exists and is typed
  console.log(result.data.name); // "Alice"
} else {
  // TypeScript knows result.error exists
  console.error(result.error.issues);
  // Handle the error without crashing
}

Why This Matters for APIs

When validating external data like API responses or user input, you rarely want your application to crash. .safeParse() gives you control: log the error, return a default value, show a user-friendly message, or retry the request.

Key Takeaway: Use .safeParse() instead of .parse() when you need to handle validation failures gracefully without throwing exceptions — perfect for API boundaries and user input validation.