Skip to main content

​
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.
CodeNameDescriptionWhen Used
-32700Parse errorInvalid JSON was receivedWhen the server receives malformed JSON that cannot be parsed
-32600Invalid requestThe JSON sent is not a valid Request objectWhen the request is missing required fields or has invalid structure
-32601Method not foundThe method does not exist or is not availableWhen a requested method is not implemented or not supported by the current connection
-32602Invalid paramsInvalid method parameter(s)When method parameters fail validation or don’t match the expected schema
-32603Internal errorInternal JSON-RPC errorWhen an unexpected error occurs during request processing

​
ACP-Specific Error Codes

These error codes are specific to the Agent Client Protocol.
CodeNameDescriptionWhen Used
-32000Authentication requiredAuthentication is required before proceedingWhen an agent requires authentication before creating sessions
-32002Resource not foundA resource (such as a file) was not foundWhen 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

Build docs developers (and LLMs) love

Get started for freeTalk to us