Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us