> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentclientprotocol/typescript-sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> JSON-RPC and ACP error code reference

## Overview

ACP uses JSON-RPC 2.0 error codes to communicate errors between clients and agents. This page lists all standard and ACP-specific error codes used in the protocol.

## Standard JSON-RPC Error Codes

These error codes are defined by the JSON-RPC 2.0 specification.

| Code     | Name             | Description                                   | When Used                                                                             |
| -------- | ---------------- | --------------------------------------------- | ------------------------------------------------------------------------------------- |
| `-32700` | Parse error      | Invalid JSON was received                     | When the server receives malformed JSON that cannot be parsed                         |
| `-32600` | Invalid request  | The JSON sent is not a valid Request object   | When the request is missing required fields or has invalid structure                  |
| `-32601` | Method not found | The method does not exist or is not available | When a requested method is not implemented or not supported by the current connection |
| `-32602` | Invalid params   | Invalid method parameter(s)                   | When method parameters fail validation or don't match the expected schema             |
| `-32603` | Internal error   | Internal JSON-RPC error                       | When an unexpected error occurs during request processing                             |

## ACP-Specific Error Codes

These error codes are specific to the Agent Client Protocol.

| Code     | Name                    | Description                                  | When Used                                                           |
| -------- | ----------------------- | -------------------------------------------- | ------------------------------------------------------------------- |
| `-32000` | Authentication required | Authentication is required before proceeding | When an agent requires authentication before creating sessions      |
| `-32002` | Resource not found      | A resource (such as a file) was not found    | When a requested file, session, or other resource cannot be located |

## Error Code Ranges

JSON-RPC 2.0 reserves specific ranges for different types of errors:

* **`-32768` to `-32000`**: Reserved for JSON-RPC specification errors
* **`-32099` to `-32000`**: Server error range (implementation-defined)
* **Custom application errors**: Should use codes outside the reserved range

## Usage Examples

### Parse Error (-32700)

```typescript theme={null}
import { RequestError } from "@agentclientprotocol/sdk";

try {
  JSON.parse(invalidJsonString);
} catch (error) {
  throw RequestError.parseError({ received: invalidJsonString });
}
```

**Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "Parse error",
    "data": {
      "received": "invalid json..."
    }
  }
}
```

### Invalid Request (-32600)

```typescript theme={null}
if (!message.id || !message.method) {
  throw RequestError.invalidRequest(
    { reason: "Missing required fields" }
  );
}
```

**Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "Invalid request",
    "data": {
      "reason": "Missing required fields"
    }
  }
}
```

### Method Not Found (-32601)

```typescript theme={null}
if (!supportedMethods.includes(method)) {
  throw RequestError.methodNotFound(method);
}
```

**Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found: custom/method",
    "data": {
      "method": "custom/method"
    }
  }
}
```

### Invalid Params (-32602)

```typescript theme={null}
import { z } from "zod";

try {
  const validatedParams = schema.parse(params);
} catch (error) {
  if (error instanceof z.ZodError) {
    throw RequestError.invalidParams(error.format());
  }
}
```

**Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "sessionId": {
        "_errors": ["Required"]
      }
    }
  }
}
```

### Internal Error (-32603)

```typescript theme={null}
try {
  await dangerousOperation();
} catch (error) {
  throw RequestError.internalError(
    { details: error.message }
  );
}
```

**Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": {
      "details": "Database connection failed"
    }
  }
}
```

### Authentication Required (-32000)

```typescript theme={null}
if (!session.isAuthenticated) {
  throw RequestError.authRequired({
    authMethods: ["oauth", "api_key"]
  });
}
```

**Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Authentication required",
    "data": {
      "authMethods": ["oauth", "api_key"]
    }
  }
}
```

### Resource Not Found (-32002)

```typescript theme={null}
const session = await getSession(sessionId);
if (!session) {
  throw RequestError.resourceNotFound(sessionId);
}
```

**Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "Resource not found: session-123",
    "data": {
      "uri": "session-123"
    }
  }
}
```

## Error Handling Best Practices

### 1. Use Specific Error Codes

Choose the most specific error code for the situation:

```typescript theme={null}
// Good: Specific error for missing resource
throw RequestError.resourceNotFound(uri);

// Avoid: Generic internal error
throw RequestError.internalError({ message: "File not found" });
```

### 2. Include Helpful Error Data

Provide additional context in the `data` field:

```typescript theme={null}
throw RequestError.invalidParams({
  field: "sessionId",
  expected: "string",
  received: typeof params.sessionId,
});
```

### 3. Handle Errors Gracefully

Catch and convert errors appropriately:

```typescript theme={null}
const requestHandler = async (method: string, params: unknown) => {
  try {
    return await handleMethod(method, params);
  } catch (error) {
    // Already a RequestError
    if (error instanceof RequestError) {
      throw error;
    }
    
    // Validation errors
    if (error instanceof z.ZodError) {
      throw RequestError.invalidParams(error.format());
    }
    
    // Unexpected errors
    throw RequestError.internalError({
      details: error.message
    });
  }
};
```

### 4. Document Custom Error Codes

If you define custom error codes (outside the reserved range), document them clearly:

```typescript theme={null}
// Custom error codes for your application
const CustomErrors = {
  RATE_LIMIT_EXCEEDED: -32001,
  SESSION_EXPIRED: -32003,
} as const;

throw new RequestError(
  CustomErrors.RATE_LIMIT_EXCEEDED,
  "Rate limit exceeded",
  { retryAfter: 60 }
);
```

## See Also

* [RequestError Class](/api/request-error) - Error class API reference
* [JSON-RPC Types](/api/jsonrpc) - JSON-RPC type definitions
* [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification#error_object) - Official error object specification