7a:T446,// Rust's Result provides type-safe return codes fn find_user_by_id(user_id: &str) -> Result { let user = user_repository::lookup(user_id) .map_err(|e| UserError::RepositoryError(e))?; user.ok_or(UserError::NotFound(user_id.to_string())) } // Caller with the ? operator for ergonomic propagation fn process_order(user_id: &str) -> Result<(), OrderError> { let user = find_user_by_id(user_id) .map_err(|e| OrderError::UserError(e))?; create_order_for_user(&user)?; send_confirmation(&user)?; Ok(()) } // Explicit handling when needed fn process_order_with_recovery(user_id: &str) -> Result<(), OrderError> { match find_user_by_id(user_id) { Ok(user) => { create_order_for_user(&user)?; send_confirmation(&user) } Err(UserError::NotFound(id)) => { log::warn!("Creating guest user for: {}", id); let guest = create_guest_user(&id)?; create_order_for_user(&guest) } Err(e) => Err(OrderError::UserError(e)), } }7b:T65d,// Exception propagation: intermediate layers don't need to handle errors public class OrderService { public void placeOrder(OrderRequest request) { // UserService.findUser() might throw UserNotFoundException // PaymentService.charge() might throw PaymentFailedException // InventoryService.reserve() might throw InsufficientStockException // None of these need try-catch here if OrderService // isn't the right place to handle them User user = userService.findUser(request.getUserId()); Payment payment = paymentService.charge(request.getPaymentInfo()); Reservation reservation = inventoryService.reserve(request.getItems()); // Only reached if ALL previous operations succeeded Order order = Order.create(user, payment, reservation); orderRepository.save(order); } } // Exceptions bubble up to wherever handling makes sense @RestController public class OrderController { @PostMapping("/orders") public ResponseEntity createOrder(@RequestBody OrderRequest request) { try { orderService.placeOrder(request); return ResponseEntity.ok().build(); } catch (UserNotFoundException e) { return ResponseEntity.status(404).body(errorFor(e)); } catch (PaymentFailedException e) { return ResponseEntity.status(402).body(errorFor(e)); } catch (InsufficientStockException e) { return ResponseEntity.status(409).body(errorFor(e)); } // Unknown exceptions propagate to global handler } }7c:T4bc,// Return codes: every error point is explicit func PlaceOrder(ctx context.Context, request OrderRequest) error { user, err := userService.FindUser(ctx, request.UserID) if err != nil { return fmt.Errorf("finding user: %w", err) } payment, err := paymentService.Charge(ctx, request.PaymentInfo) if err != nil { return fmt.Errorf("charging payment: %w", err) } reservation, err := inventoryService.Reserve(ctx, request.Items) if err != nil { // We might need to refund the payment we charged if refundErr := paymentService.Refund(ctx, payment.ID); refundErr != nil { // Log refund failure but return original error log.Printf("CRITICAL: refund failed after inventory error: %v", refundErr) } return fmt.Errorf("reserving inventory: %w", err) } order := CreateOrder(user, payment, reservation) if err := orderRepo.Save(ctx, order); err != nil { // Compensating transactions are explicitly handled paymentService.Refund(ctx, payment.ID) inventoryService.Release(ctx, reservation.ID) return fmt.Errorf("saving order: %w", err) } return nil }7d:T471,// Rust's Result with ? operator: explicit but ergonomic fn place_order(request: &OrderRequest) -> Result { let user = user_service::find_user(&request.user_id) .map_err(OrderError::User)?; let payment = payment_service::charge(&request.payment_info) .map_err(OrderError::Payment)?; // Scoped cleanup on inventory failure let reservation = match inventory_service::reserve(&request.items) { Ok(r) => r, Err(e) => { // Explicit compensating action if let Err(refund_err) = payment_service::refund(&payment.id) { log::error!("CRITICAL: refund failed: {:?}", refund_err); } return Err(OrderError::Inventory(e)); } }; let order = Order::new(user, payment, reservation); order_repo::save(&order) .map_err(|e| { // Compensating transactions on save failure let _ = payment_service::refund(&payment.id); let _ = inventory_service::release(&reservation.id); OrderError::Persistence(e) })?; Ok(order) }7e:T502,**The "Ignored Error" Problem:** Return-code critics correctly identify a critical weakness: forgetting to check errors is trivially easy and produces silent failures. ```go // This compiles and runs—but silently loses the error user, _ := FindUser(userId) // Error ignored with blank identifier ProcessUser(user) // Proceeds with nil user // Even worse: implicit ignore user, err := FindUser(userId) if user != nil { // Should check err != nil first! ProcessUser(user) } ``` This is not theoretical. Studies of large codebases find significant percentages of error returns are unchecked. The fix is discipline and tooling (linters that warn on ignored errors), but the failure mode is real. **The "Hidden Throw" Problem:** Exception critics correctly identify the inverse weakness: every function call might exit your function, and you often don't know which ones. ```java void transfer(Account from, Account to, Money amount) { from.debit(amount); // Might throw? to.credit(amount); // Might throw—but from is already debited! } ``` Without explicit documentation or checked exceptions, callers cannot know which operations throw. The fix is documentation discipline and careful contract design, but the failure mode is real.7f:T742,// Deep call stack: exceptions avoid error threading public class DocumentProcessor { public ProcessedDocument process(RawDocument doc) { // Exceptions from ANY of these nested operations // propagate directly to our caller without intermediate handling Document parsed = parser.parse(doc); // Might throw ParseException Document validated = validator.validate(parsed); // Might throw ValidationException Document enriched = enricher.enrich(validated); // Might throw EnrichmentException return transformer.transform(enriched); // Might throw TransformException } } // Constructor failure: no return value exists public class DatabaseConnection { private final Connection underlyingConnection; public DatabaseConnection(String connectionString) throws ConnectionException { try { this.underlyingConnection = DriverManager.getConnection(connectionString); this.underlyingConnection.setAutoCommit(false); validateConnection(this.underlyingConnection); } catch (SQLException e) { throw new ConnectionException("Failed to establish connection", e); } // If we reach here, object is fully initialized and valid } } // Rich context with exception chaining public void processPayment(PaymentRequest request) throws PaymentException { try { gateway.submit(request); } catch (NetworkException e) { throw new PaymentException( "Payment gateway unreachable", e, // Original exception preserved PaymentErrorCode.GATEWAY_UNAVAILABLE, Map.of( "gatewayHost", gateway.getHost(), "timeout", gateway.getTimeout(), "requestId", request.getId() ) ); } }80:T419,// Partial success: batch operation with per-item results fn process_items(items: &[Item]) -> BatchResult { let mut results = BatchResult::new(); for item in items { match process_single_item(item) { Ok(processed) => results.add_success(processed), Err(e) => results.add_failure(item.id.clone(), e), } } results // Contains both successes and failures—caller decides policy } // Functional composition with Result fn process_order(order_id: &str) -> Result { fetch_order(order_id) .and_then(|order| validate_order(&order)) .and_then(|validated| enrich_order(&validated)) .and_then(|enriched| transform_order(&enriched)) .map(|transformed| finalize_order(&transformed)) } // Performance-critical: no exception overhead #[inline] fn fast_parse(data: &[u8]) -> Result { if data.len() < HEADER_SIZE { return Err(ParseError::TooShort); } // ... parsing logic Ok(parsed) }81:T651,// Hybrid: Optional for "maybe", exceptions for errors public class UserRepository { // Not found is normal—return Optional public Optional findByEmail(String email) { return Optional.ofNullable(doQuery(email)); } // Must exist—throw if not found public User getById(String id) throws UserNotFoundException { return findById(id) .orElseThrow(() -> new UserNotFoundException(id)); } // Database failure is exceptional—let it throw private User doQuery(String email) { // SQLException is wrapped in DataAccessException by Spring // and thrown as unchecked—infrastructure errors propagate return jdbcTemplate.queryForObject( "SELECT * FROM users WHERE email = ?", userMapper, email ); } } // Service layer uses both patterns appropriately public class AuthService { public AuthResult authenticate(Credentials creds) { Optional maybeUser = userRepo.findByEmail(creds.email()); if (maybeUser.isEmpty()) { return AuthResult.failure("User not found"); // Return code for expected case } User user = maybeUser.get(); if (!passwordHasher.verify(creds.password(), user.getPasswordHash())) { return AuthResult.failure("Invalid password"); // Return code for expected case } // Token generation failure is exceptional—let it throw String token = tokenService.generate(user); return AuthResult.success(token); } }82:T4f4,// TypeScript with Result type for explicit error handling type Result = { ok: true; value: T } | { ok: false; error: E }; function ok(value: T): Result { return { ok: true, value }; } function err(error: E): Result { return { ok: false, error }; } // Validation returns Result—failure is expected function validateOrder(order: OrderInput): Result { const errors: ValidationError[] = []; if (!order.items || order.items.length === 0) { errors.push({ field: 'items', message: 'Order must have items' }); } if (order.total <= 0) { errors.push({ field: 'total', message: 'Total must be positive' }); } if (errors.length > 0) { return err(errors); } return ok(order as ValidatedOrder); } // Repository can throw for infrastructure errors but returns Result for domain async function findUserById(id: string): Promise> { const row = await db.query('SELECT * FROM users WHERE id = ?', [id]); // db.query throws on connection errors—infrastructure exceptions if (!row) { return err('not_found'); // Expected case: return code } return ok(mapToUser(row)); }72:{"json":{"id":"seed_ae2d525650d959a49fd10b50107e5221","slug":"error-handling-in-apis","category":"System Design (LLD)","topic":"Error Handling in APIs","title":"Error Handling in APIs","description":"Master the art and science of API error handling. Learn when to use exceptions versus error codes, understand checked versus unchecked exceptions, design clear error responses, and document error conditions to create APIs that fail gracefully and communicate failures effectively.","difficulty":"INTERMEDIATE","estimatedMinutes":75,"pages":[{"id":"seed_c95560913965f9ac6af5b772fb1a5787","title":"Exceptions vs Error Codes","order":0,"content":[{"id":"opening-hook","title":"The Fundamental Question of Failure Signaling","content":[{"data":{"content":"Every API operation can fail. Networks drop packets. Resources become unavailable. Inputs violate constraints. Business rules prohibit actions. The question isn't *whether* your API will encounter errors—it's *how* you will communicate those errors to callers.\n\nThis decision—exceptions versus error codes—is one of the oldest and most consequential debates in software design. It affects code readability, error propagation, performance characteristics, and the cognitive load imposed on API consumers. Getting it wrong doesn't just create bugs; it creates entire categories of unhandled failures lurking in production systems."},"type":"text"},{"data":{"icon":"Target","title":"What You Will Learn","content":"By the end of this page, you will understand the fundamental mechanics of both exception-based and return-code-based error handling, their respective philosophies, when each approach shines (and fails), and how to make principled decisions based on context rather than dogma.","variant":"info"},"type":"callout"}]},{"id":"understanding-paradigms","title":"Understanding the Two Paradigms","content":[{"data":{"content":"Before analyzing tradeoffs, we need precise definitions. Both approaches have evolved over decades, and understanding their mechanics is essential to evaluating them fairly.\n\n**Exception-Based Error Handling:**\n\nExceptions are language-level constructs that allow a function to signal failure by *throwing* an object (the exception) which propagates up the call stack until *caught* by an enclosing handler. The normal return path is bypassed entirely.\n\n**Return-Code Error Handling:**\n\nReturn codes embed error information in the function's return value. The caller receives data that may indicate success or failure, and must explicitly inspect the result to detect errors. The control flow remains linear—no stack unwinding occurs."},"type":"text"},{"data":{"fileName":"error-paradigms-comparison","languages":[{"code":"// Exception-based: errors interrupt normal flow\npublic User findUserById(String userId) throws UserNotFoundException {\n User user = userRepository.lookup(userId);\n if (user == null) {\n // Throw interrupts execution and propagates up\n throw new UserNotFoundException(\"No user with ID: \" + userId);\n }\n return user; // Only reached if no exception\n}\n\n// Caller code\npublic void processOrder(String userId) {\n try {\n User user = findUserById(userId);\n // Happy path continues here\n createOrderForUser(user);\n sendConfirmation(user);\n } catch (UserNotFoundException e) {\n // Error handling separated from main logic\n log.error(\"Order failed: {}\", e.getMessage());\n notifySupport(e);\n }\n}","label":"Exception-Based (Java)","value":"java"},{"code":"// Return-code based: errors as values\nfunc FindUserById(userId string) (*User, error) {\n user, err := userRepository.Lookup(userId)\n if err != nil {\n return nil, fmt.Errorf(\"user lookup failed: %w\", err)\n }\n if user == nil {\n return nil, errors.New(\"no user with ID: \" + userId)\n }\n return user, nil // Explicit nil error on success\n}\n\n// Caller code\nfunc ProcessOrder(userId string) error {\n user, err := FindUserById(userId)\n if err != nil {\n // Error handling interleaved with main logic\n log.Printf(\"Order failed: %v\", err)\n notifySupport(err)\n return err\n }\n // Happy path continues only after explicit check\n if err := CreateOrderForUser(user); err != nil {\n return err\n }\n return SendConfirmation(user)\n}","label":"Return-Code (Go)","value":"go"},{"code":"$7a","label":"Return-Code (Rust)","value":"rust"}]},"type":"code"},{"data":{"icon":"Info","title":"Language Philosophy Matters","content":"Languages encode strong opinions about error handling. Java makes exceptions first-class. Go rejects exceptions entirely. Rust elevates return codes with type system support. Understanding these choices helps you work with—not against—your language's grain.","variant":"note"},"type":"callout"}],"titleType":"number","titleNumber":1},{"id":"philosophy-exceptions","title":"The Philosophy Behind Exceptions","content":[{"data":{"content":"Exceptions emerged from a specific philosophical stance: **errors are not normal returns**. When a function fails, it shouldn't pretend to return normally. The call contract was violated, and the caller should be *forced* to acknowledge this violation.\n\nThis philosophy manifests in several design properties:"},"type":"text"},{"data":{"items":["**Separation of Concerns** — Normal code handles the happy path. Exception handlers deal with failures. This separation makes both easier to read and reason about.","**Mandatory Acknowledgment** — Uncaught exceptions terminate the program (or thread). You cannot *accidentally* ignore an error. Forgetting to check a return code is impossible.","**Structured Propagation** — Exceptions automatically propagate through nested call stacks. Intermediate functions don't need to explicitly pass errors upward—they flow naturally.","**Rich Error Context** — Exception objects carry type information, messages, stack traces, and custom data. Debugging is easier because errors are self-describing.","**Transaction Rollback Semantics** — The unwinding mechanism supports RAII patterns and finally blocks, ensuring resources are released even when errors occur."],"title":{"icon":"Lightbulb","text":"Core Principles of Exception-Based Design","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"fileName":"exception-automatic-propagation.java","languages":[{"code":"$7b","label":"Java","value":"java"}]},"type":"code"},{"data":{"content":"**The Invisible Try-Block:**\n\nA subtle but crucial aspect of exceptions: **every function body is implicitly wrapped in an invisible try-block**. Any throwable operation can exit the function at any line. This makes code appear simpler but requires assuming any line might not complete.\n\nConsider the implications:\n\n```java\nvoid processData() {\n Resource r1 = acquire(); // Line completes\n Resource r2 = acquire(); // Throws! r1 is acquired but what happens?\n process(r1, r2); // Never reached\n release(r1);\n release(r2);\n}\n```\n\nWithout proper resource management (try-finally, try-with-resources, or RAII), exceptions create resource leaks. The solution is well-known—but the problem exists because exceptions allow *any* line to exit the function."},"type":"text"}],"titleType":"number","titleNumber":2},{"id":"philosophy-return-codes","title":"The Philosophy Behind Return Codes","content":[{"data":{"content":"Return-code advocates argue from a fundamentally different premise: **errors are just data**. A function that can fail returns a union type—either a success value or an error value. There's nothing magical about failure; it's simply one possible outcome.\n\nThis philosophy produces distinctly different code characteristics:"},"type":"text"},{"data":{"items":["**Explicit Control Flow** — Every potential failure point is visible in the code. You can trace exactly where errors are checked and propagated.","**Local Reasoning** — A function's behavior is fully determined by its signature and body. No hidden control flow jumps exist. What you see is what happens.","**Caller Authority** — The caller decides whether to handle, propagate, or transform errors. There's no 'force' mechanism—all handling is explicit choice.","**Type System Integration** — Modern return codes (Rust's Result, Haskell's Either) leverage the type system to ensure errors are structurally accounted for.","**Performance Predictability** — No hidden stack unwinding, no exception table lookups. Error handling costs what you see it costs."],"title":{"icon":"Target","text":"Core Principles of Return-Code Design","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"fileName":"return-code-explicit-flow","languages":[{"code":"$7c","label":"Go","value":"go"},{"code":"$7d","label":"Rust","value":"rust"}]},"type":"code"},{"data":{"icon":"Lightbulb","title":"The Visibility Advantage","content":"Notice how the return-code examples make compensating transactions visible. When charging a payment before reserving inventory, you must consider what happens if inventory reservation fails. This explicit handling catches design issues that exception-based code might hide until production.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":3},{"id":"critical-tradeoffs","title":"Critical Tradeoffs Analysis","content":[{"data":{"content":"Neither approach is universally superior. Each trades certain benefits for others. Understanding these tradeoffs deeply enables principled decision-making."},"type":"text"},{"data":{"rows":[["**Error Visibility**","Errors are hidden in control flow; any line might throw","Every error point is explicit in code"],["**Propagation Effort**","Automatic—exceptions bubble up without code","Manual—every layer must check and forward"],["**Ignoring Errors**","Impossible to ignore (unhandled exception terminates)","Easy to ignore (just don't check the return)"],["**Code Volume**","Less code for propagation-heavy cases","More code due to explicit checking"],["**Control Flow**","Non-local jumps through stack unwinding","Strictly local—returns exit only current function"],["**Performance**","Zero-cost on happy path; costly when thrown","Small constant cost on every fallible call"],["**Debugging**","Stack traces included automatically","Must compose error context manually"],["**Refactoring Risk**","Adding throws changes implicit contracts","Adding error returns changes explicit signatures"]],"caption":"Exception vs Return Code: Key Tradeoffs","headers":["Characteristic","Exceptions","Return Codes"]},"type":"table"},{"data":{"content":"$7e"},"type":"text"}],"titleType":"number","titleNumber":4},{"id":"when-use-exceptions","title":"When to Use Exceptions","content":[{"data":{"content":"Exceptions excel in specific contexts. Use them when their strengths align with your needs and their weaknesses are manageable."},"type":"text"},{"data":{"items":["**Deep Call Stacks with Centralized Handling** — When errors originate deep in the call hierarchy but handling occurs at a high level (e.g., HTTP request handlers), exceptions eliminate error-threading code through every intermediate layer.","**Truly Exceptional Conditions** — Events that should 'never' happen under normal operation (configuration parse failures, violated invariants, unreachable code paths) benefit from exception semantics—they should loudly interrupt.","**Constructor Failures** — Constructors don't have return values. If object construction can fail, exceptions are the natural mechanism (or alternatively, factory methods returning optional/result types).","**Framework Integration** — When using frameworks that expect exceptions (most Java frameworks, .NET frameworks), working *with* the framework's grain is almost always better than fighting it.","**Rich Error Context Required** — When errors need stack traces, chained causes, and structured data for debugging, exception objects naturally support this richness."],"title":{"icon":"CheckCircle","text":"Contexts Where Exceptions Shine","type":"icon","color":"primary","variant":"outline-circle"},"variant":"glass"},"type":"list"},{"data":{"fileName":"exceptions-ideal-cases.java","languages":[{"code":"$7f","label":"Java","value":"java"}]},"type":"code"}],"titleType":"number","titleNumber":5},{"id":"when-use-return-codes","title":"When to Use Return Codes","content":[{"data":{"content":"Return codes excel in their own contexts. Use them when explicit control flow, performance predictability, or local reasoning matters most."},"type":"text"},{"data":{"items":["**Expected Failure Cases** — When 'failure' is a normal outcome (user not found, item out of stock, validation rejection), return codes treat it as data rather than exceptional interruption.","**Performance-Critical Paths** — In tight loops or hot paths where exception unwinding costs matter, return codes provide predictable overhead.","**Systems Programming** — Low-level code, FFI boundaries, and system calls naturally use return codes. Crossing language boundaries with exceptions is complex.","**Partial Success Scenarios** — Operations that can partially succeed (batch processing, multi-resource operations) express results better as data than as thrown exceptions.","**Functional Composition** — Return codes (especially Result/Either types) compose with map, flatMap, and other combinators. Exception handling doesn't compose as cleanly."],"title":{"icon":"CheckCircle","text":"Contexts Where Return Codes Shine","type":"icon","color":"primary","variant":"outline-circle"},"variant":"glass"},"type":"list"},{"data":{"fileName":"return-codes-ideal-cases","languages":[{"code":"// Expected failure: not finding a user is normal, not exceptional\nfunc FindUserByEmail(email string) (*User, error) {\n user, err := db.QueryOne(\"SELECT * FROM users WHERE email = ?\", email)\n if err == sql.ErrNoRows {\n return nil, nil // No user found—return nil, nil (not an error!)\n }\n if err != nil {\n return nil, fmt.Errorf(\"query failed: %w\", err)\n }\n return user, nil\n}\n\n// Caller handles \"not found\" as a normal case\nfunc LoginOrRegister(email string) (*User, error) {\n user, err := FindUserByEmail(email)\n if err != nil {\n return nil, err // Actual error: propagate\n }\n if user == nil {\n return RegisterNewUser(email) // Normal flow: create new user\n }\n return user, nil\n}","label":"Go","value":"go"},{"code":"$80","label":"Rust","value":"rust"}]},"type":"code"},{"data":{"icon":"Lightbulb","title":"The 'Expected' vs 'Exceptional' Heuristic","content":"A useful rule: if the caller will almost always need to handle this condition explicitly, use return codes. If the condition represents a genuine surprise that most callers will propagate, use exceptions. 'User not found' is expected; 'database connection lost' is exceptional.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":6},{"id":"hybrid-approaches","title":"Hybrid Approaches and Language-Specific Patterns","content":[{"data":{"content":"Many real-world systems use hybrid approaches, leveraging exceptions for some error categories and return codes for others. Modern languages increasingly provide mechanisms that blend both philosophies."},"type":"text"},{"data":{"left":[{"data":{"items":["**Exceptions for errors, return codes for expected failures** — Database errors throw; 'not found' returns null/empty","**Optional/Maybe for absence** — Use Optional when value might not exist, exceptions when it must exist but lookup failed","**Result types in exception-based languages** — Java's vavr library, C#'s language-ext provide Result types","**Domain exceptions only** — Throw only domain-specific exceptions; infrastructure errors use return codes or logging"],"title":{"icon":"Zap","text":"Common Hybrid Patterns","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"}],"right":[{"data":{"items":["**Java** — Checked exceptions for recoverable errors, unchecked for bugs; increasingly Optional for absence","**C#** — Unchecked exceptions only; TryParse pattern for expected failures; nullable reference types","**Kotlin** — Exceptions exist but return types often preferred; sealed classes for error hierarchies","**TypeScript** — Exceptions available but Result types increasingly popular in type-safe code"],"title":{"icon":"Code2","text":"Language-Specific Idioms","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"}]},"type":"two-column"},{"data":{"fileName":"hybrid-approach","languages":[{"code":"$81","label":"Java Hybrid","value":"java"},{"code":"$82","label":"TypeScript Result","value":"typescript"}]},"type":"code"}],"titleType":"number","titleNumber":7},{"id":"api-design-guidelines","title":"API Design Guidelines for Error Strategy Choice","content":[{"data":{"content":"When designing an API, your choice of error strategy affects every consumer. Here are principles that guide good decisions:"},"type":"text"},{"data":{"type":"ordered","items":["**Match Your Ecosystem** — If every other library in your ecosystem uses exceptions, using return codes creates friction. Consistency with surrounding code matters more than theoretical purity.","**Be Predictable** — Pick a strategy and apply it consistently. An API that sometimes throws and sometimes returns null for similar conditions creates confusion and bugs.","**Make Failure Explicit in Signatures** — Whether throws declarations, Result types, or documentation, the signature should communicate that failure is possible.","**Distinguish Error Categories** — Use different mechanisms for different categories. Validation errors might return; infrastructure failures might throw; business rule violations might use custom types.","**Preserve Error Context** — Whether exception causes or wrapped errors, ensure debugging information flows from origin to handler without loss."],"title":{"icon":"Target","text":"Principles for API Error Strategy","type":"icon","color":"primary","variant":"outline-circle"},"variant":"glass"},"type":"list"},{"data":{"icon":"AlertCircle","title":"The Worst Choice: Inconsistency","content":"An API that inconsistently mixes strategies—sometimes throwing, sometimes returning null, sometimes returning error codes—is worse than either consistent approach. Callers never know what to expect and invariably get it wrong.","variant":"warning"},"type":"callout"},{"data":{"rows":[["Internal library in exception-based language","Exceptions","Match ecosystem; leverage language support"],["Public API with diverse consumers","Consider both + clear documentation","Different consumers have different needs"],["Performance-critical inner loop","Return codes","Avoid exception overhead in hot paths"],["Operations that commonly 'fail'","Return codes or Optional","'User not found' isn't exceptional"],["Operations that rarely fail","Exceptions","Failure is genuinely surprising"],["FFI/cross-language boundary","Return codes","Exceptions don't cross boundaries cleanly"],["Constructor/initialization","Exceptions or factory methods","Constructors can't return error codes"]],"caption":"Decision Matrix: Choosing Error Strategy by Context","headers":["Context","Recommended Approach","Reasoning"]},"type":"table"}],"titleType":"number","titleNumber":8},{"id":"summary","title":"Summary: Exceptions vs Error Codes","content":[{"data":{"content":"We've explored the fundamental mechanics, philosophies, and tradeoffs of exception-based versus return-code-based error handling. Let's consolidate the key insights:"},"type":"text"},{"data":{"type":"ordered","items":["**Exceptions and return codes represent different philosophies** — Exceptions treat errors as interrupting events; return codes treat them as data. Neither is universally correct.","**Exceptions excel at automatic propagation and mandatory handling** — When errors should bubble up through many layers, exceptions reduce boilerplate.","**Return codes excel at explicitness and predictability** — When you need to see every failure point and control handling locally, return codes shine.","**The 'expected vs exceptional' heuristic guides decisions** — Expected failures (not found, validation failed) work well as return codes; surprising failures (connection lost, invariant violated) work well as exceptions.","**Hybrid approaches are common and valid** — Many systems use exceptions for infrastructure errors and return codes for domain logic. Consistency within categories matters.","**Language ecosystem matters enormously** — Work with your language's grain. Fighting the ecosystem creates more problems than theoretical purity solves."],"title":{"icon":"CheckCircle","text":"Key Takeaways","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"content":"**What's next:**\n\nIn languages that support exceptions, you face a second decision: checked versus unchecked exceptions. This debate—especially fierce in the Java community—reveals deeper questions about contract enforcement, compile-time safety, and API evolution. The next page explores this nuanced topic in depth."},"type":"text"},{"data":{"icon":"CheckCircle","title":"Page Complete","content":"You now understand the fundamental choice between exceptions and return codes. This isn't a matter of preference—it's a design decision with concrete tradeoffs that should be made deliberately based on context, ecosystem, and requirements.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":9}],"isLocked":false},{"id":"seed_9f91ef93e172f5f912bd93d8dd13b4be","title":"Checked vs Unchecked Exceptions","order":1,"content":null,"isLocked":true},{"id":"seed_bc76c004176a26930158ed46d23d3a5c","title":"Error Response Design","order":2,"content":null,"isLocked":true},{"id":"seed_f35c684e1b14de57e3989399c5a6f315","title":"Error Documentation","order":3,"content":null,"isLocked":true}]}}