RequestError Class

JSON-RPC error handling for ACP requests

Overview

The RequestError class represents errors that occur during JSON-RPC method execution in ACP connections. It follows the JSON-RPC 2.0 error object specification and provides static factory methods for creating standard error types.

Constructor

constructor(
  public code: number,
  message: string,
  data?: unknown
)

Creates a new RequestError with the specified error code, message, and optional additional data.

Parameters:

• code (number) - The JSON-RPC error code
• message (string) - Human-readable error message
• data (unknown, optional) - Additional error information

Properties

code

code: number

The numeric error code following JSON-RPC 2.0 conventions.

message

message: string

Human-readable description of the error.

data

data?: unknown

Optional additional information about the error, such as validation details or context.

Static Factory Methods

parseError

static parseError(data?: unknown, additionalMessage?: string): RequestError

Creates a parse error (code: -32700).

Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.

Parameters:

• data (unknown, optional) - Additional error data
• additionalMessage (string, optional) - Additional context to append to the error message

Returns: RequestError with code -32700

Example:

throw RequestError.parseError({ received: invalidJson });

invalidRequest

static invalidRequest(data?: unknown, additionalMessage?: string): RequestError

Creates an invalid request error (code: -32600).

The JSON sent is not a valid Request object.

Parameters:

• data (unknown, optional) - Additional error data
• additionalMessage (string, optional) - Additional context to append to the error message

Returns: RequestError with code -32600

Example:

throw RequestError.invalidRequest({ reason: "Missing required field 'id'" });

methodNotFound

static methodNotFound(method: string): RequestError

Creates a method not found error (code: -32601).

The method does not exist or is not available.

Parameters:

• method (string) - The method name that was not found

Returns: RequestError with code -32601 and the method name in data

Example:

throw RequestError.methodNotFound("unknown/method");

invalidParams

static invalidParams(data?: unknown, additionalMessage?: string): RequestError

Creates an invalid params error (code: -32602).

Invalid method parameter(s).

Parameters:

• data (unknown, optional) - Additional error data (often validation details)
• additionalMessage (string, optional) - Additional context to append to the error message

Returns: RequestError with code -32602

Example:

throw RequestError.invalidParams(zodError.format());

internalError

static internalError(data?: unknown, additionalMessage?: string): RequestError

Creates an internal error (code: -32603).

Internal JSON-RPC error.

Parameters:

• data (unknown, optional) - Additional error data
• additionalMessage (string, optional) - Additional context to append to the error message

Returns: RequestError with code -32603

Example:

throw RequestError.internalError({ details: error.message });

authRequired

static authRequired(data?: unknown, additionalMessage?: string): RequestError

Creates an authentication required error (code: -32000).

Parameters:

• data (unknown, optional) - Additional error data
• additionalMessage (string, optional) - Additional context to append to the error message

Returns: RequestError with code -32000

Example:

throw RequestError.authRequired({ authMethods: ["oauth"] });

resourceNotFound

static resourceNotFound(uri?: string): RequestError

Creates a resource not found error (code: -32002).

Resource, such as a file, was not found.

Parameters:

• uri (string, optional) - The URI of the missing resource

Returns: RequestError with code -32002 and URI in data (if provided)

Example:

throw RequestError.resourceNotFound("/path/to/missing/file.txt");

Instance Methods

toResult

toResult<T>(): Result<T>

Converts the RequestError to a JSON-RPC Result object with an error field.

Returns: A Result object containing the error information

Example:

const error = RequestError.methodNotFound("test/method");
return error.toResult();
// Returns: { error: { code: -32601, message: "Method not found: test/method", data: { method: "test/method" } } }

toErrorResponse

toErrorResponse(): ErrorResponse

Converts the RequestError to a JSON-RPC ErrorResponse object.

Returns: An ErrorResponse object with code, message, and optional data

Example:

const error = RequestError.invalidParams({ field: "sessionId" });
const errorResponse = error.toErrorResponse();
// Returns: { code: -32602, message: "Invalid params", data: { field: "sessionId" } }

Usage in Request Handlers

const requestHandler = async (method: string, params: unknown): Promise<unknown> => {
  // Method not found
  if (method === "unknown/method") {
    throw RequestError.methodNotFound(method);
  }

  // Invalid parameters
  try {
    const validatedParams = schema.parse(params);
  } catch (error) {
    throw RequestError.invalidParams(error.format());
  }

  // Resource not found
  const file = await readFile(uri);
  if (!file) {
    throw RequestError.resourceNotFound(uri);
  }

  // Authentication required
  if (!isAuthenticated) {
    throw RequestError.authRequired();
  }

  return result;
};

See Also

• Error Codes - Complete list of error codes
• JSON-RPC Types - JSON-RPC type definitions