Error Handling Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• src/getErrorMessage.ts
• src/client.ts
• src/output.ts
• src/commands/content/createCommand.ts
• src/commands/tasks/statusCommand.ts
• tests/client.test.ts

Introduction

The Recoup CLI implements a centralized and consistent error handling strategy designed to provide clear feedback to users when operations fail. This strategy spans from the low-level HTTP client to the command-level action handlers, ensuring that both network-level failures and application-level validation errors are caught, formatted, and reported appropriately.

The primary goal of this system is to prevent silent failures, handle non-standard error objects gracefully, and provide the user with actionable error messages before exiting the process with a non-zero status code.

Core Architecture

The error handling architecture is built on three main layers: API response validation, utility-based message extraction, and standardized output formatting.

API Layer Handling

The src/client.ts module is responsible for the first line of defense. It validates the HTTP response status and the internal application status returned by the Recoup API.

• HTTP Status Check: If response.ok is false, the client throws an Error.
• API Status Check: Even if the HTTP request is technically successful (200 OK), the CLI checks the status field in the JSON body. If status === "error", an Error is thrown using the error or message field from the response.

Sources: src/client.ts:33-36, src/client.ts:58-61

Error Message Extraction

Because JavaScript can throw values that are not instances of the Error class (e.g., strings), the CLI uses a utility function getErrorMessage to ensure a string representation is always available.

export function getErrorMessage(err: unknown): string {
  return err instanceof Error ? err.message : String(err);
}

Sources: src/getErrorMessage.ts:1-3

Terminal Output and Process Exit

The src/output.ts module provides the printError function, which serves as the final sink for all caught errors. It ensures that error messages are prefixed with "Error: ", sent to stderr, and that the application terminates with exit code 1.

Sources: src/output.ts:36-39

Error Flow Diagram

The following diagram illustrates the flow of an error from an API request failure through the CLI's handling logic.

The flow ensures that regardless of where the failure occurs (network or logic), the user receives a standardized terminal message.
Sources: src/client.ts, src/output.ts, src/getErrorMessage.ts

Logic and Validation Errors

Beyond API failures, individual commands implement local validation logic. These validations throw standard Errors that are caught by the same try/catch blocks used for API calls.

Common Validation Scenarios

Scenario	Error Message Example	Source File
Invalid batch count	--batch must be a positive integer	src/commands/content/createCommand.ts:19
Invalid enum value	--caption-length must be one of: short, medium, long	src/commands/content/createCommand.ts:21
Missing API data	Response did not include any run IDs	src/commands/content/createCommand.ts:46
Missing required ID	Provide --prompt or use --preset	src/commands/songs.ts:15

Implementation Example

Typical command implementation wraps the entire execution logic in a try/catch block to ensure all potential failures (validation, network, or parsing) are handled by the centralized printError utility.

action(async opts => {
  try {
    // 1. Local Validation
    if (invalid) throw new Error("Validation failed");

    // 2. API Request
    const data = await get("/api/resource", { id: opts.id });

    // 3. Response Processing
    process(data);
  } catch (err) {
    // 4. Centralized Handling
    printError(getErrorMessage(err));
  }
});

Sources: src/commands/content/createCommand.ts:17-57, src/commands/tasks/statusCommand.ts:11-33

Summary

The Recoup CLI error handling strategy relies on a strict try/catch pattern across all subcommands. It leverages the getErrorMessage utility to normalize error types and the printError utility to ensure consistent terminal output and exit codes. By validating both HTTP-level success and application-level status codes in the core HTTP client, the CLI provides a robust interface that accurately reflects the state of the Recoup platform.