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)

import { RequestError } from "@agentclientprotocol/sdk";

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

Response:

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

Invalid Request (-32600)

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

Response:

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

Method Not Found (-32601)

if (!supportedMethods.includes(method)) {
  throw RequestError.methodNotFound(method);
}

Response:

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

Invalid Params (-32602)

import { z } from "zod";

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

Response:

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

Internal Error (-32603)

try {
  await dangerousOperation();
} catch (error) {
  throw RequestError.internalError(
    { details: error.message }
  );
}

Response:

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

Authentication Required (-32000)

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

Response:

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

Resource Not Found (-32002)

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

Response:

{
  "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:

// 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:

throw RequestError.invalidParams({
  field: "sessionId",
  expected: "string",
  received: typeof params.sessionId,
});

3. Handle Errors Gracefully

Catch and convert errors appropriately:

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:

// 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 - Error class API reference
• JSON-RPC Types - JSON-RPC type definitions
• JSON-RPC 2.0 Specification - Official error object specification