Error Type Inference and Handling in tRPC
You'll learn how tRPC automatically infers error types from your procedures and what compile-time guarantees exist when handling errors on the client side.
The Error Type Challenge
In traditional REST APIs, you have no idea what shape errors might take—you get back any or unknown and hope for the best. tRPC changes this by making errors part of your type contract, flowing from server procedures to client error handlers with full type safety.
How tRPC Shapes Error Types
When you throw errors in tRPC procedures (whether manually or through validation failures), those error types become part of your AppRouter type definition. The tRPC client then infers the possible error shapes for each procedure call.
Think of it like a contract that says: "This procedure might succeed with type X, or fail with error shape Y." Your client code gets IntelliSense for both paths.
Type-Safe Error Handling
On the client side, tRPC provides typed error objects when calls fail. The error structure includes:
data: Contains error details like validation issues, HTTP status codes, and custom error datashape: The formatted error matching your server's error formattermessage: A string description of what went wrong
Because these flow through your AppRouter type, you get autocomplete when accessing error properties and compile-time checks ensuring you handle errors that actually exist.
Runtime and Compile-Time Guarantees
tRPC gives you the best of both worlds: runtime validation through Zod schemas catches malformed inputs before they reach your procedure logic, while TypeScript ensures your error-handling code references valid error properties. You won't ship code that tries to access error.data.zodError if that property doesn't exist in your error formatter's output.
Key Takeaway: tRPC makes errors a typed part of your API contract—both the error shapes and their properties are inferred end-to-end, giving you autocomplete and compile-time safety when handling failures on the client.