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

# Errors

> Error handling in the Agent Client Protocol

Failed requests return a [JSON-RPC 2.0 error object](https://www.jsonrpc.org/specification#error_object):

* `code`: an integer identifying the kind of error
* `message`: a short human-readable description
* `data` (optional): additional information whose shape depends on the code

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": { "sessionId": "sess_abc123def456" }
  }
}
```

## Error Codes

| Code | Message | Meaning |
| - | - | - |
| `-32700` | Parse error | The message is not valid JSON. |
| `-32600` | Invalid request | The message is not a valid request object, or a request other than `initialize` arrived before initialization. |
| `-32601` | Method not found | The receiver does not implement the method. |
| `-32602` | Invalid params | The parameters are malformed or contain a value the receiver does not support. |
| `-32603` | Internal error | The receiver failed unexpectedly. |
| `-32800` | Request cancelled | The request was [cancelled](https://agentclientprotocol.com/protocol/v1/cancellation.md). |
| `-32000` | Authentication required | The request requires [authentication](https://agentclientprotocol.com/protocol/v1/authentication.md) first. |
| `-32002` | Resource not found | A referenced resource, such as a session or file, does not exist. |

Receivers **MUST** treat an unrecognized code as a generic failure. Implementation-specific errors **SHOULD** use codes outside `-32768` to `-32000`, which is reserved for JSON-RPC and ACP.

## Common Cases

### Unknown Methods

A receiver that does not implement a method, or receives a capability-gated method it did not advertise, **SHOULD** respond with `-32601`.

### Invalid Parameters

Malformed parameters and unsupported values get `-32602`. For example, an invalid `session/list` cursor, or an unknown `configId` or value in `session/set_config_option`. The same applies to an unknown mode in `session/set_mode`.

### Unknown Sessions

If a session-scoped request names a session that does not exist or is not active on the connection, the Agent **SHOULD** respond with `-32002` and set `data.sessionId` to the requested ID. A session is active once it is created, loaded or resumed on the connection, until it is closed.

This applies to `session/prompt`, `session/set_mode`, `session/set_config_option` and `session/close`, and to `session/load` or `session/resume` of a session that does not exist. Deleting a session that does not exist still succeeds; see [Deleting Sessions](https://agentclientprotocol.com/protocol/v1/session-delete.md).

Clients **SHOULD** respond with `-32002` when `fs/read_text_file` names a file that does not exist, or a `terminal/*` method names an unknown terminal.

### Requests Before Initialization

Agents **SHOULD** reject any request other than `initialize` that arrives before initialization completes with `-32600`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.