Error Codes

AHP uses JSON-RPC 2.0 error codes. In addition to the standard JSON-RPC codes, AHP defines application-specific error codes in the -32000 to -32099 range.

JSON Schema: errors.schema.json

Standard JSON-RPC Codes

These codes are defined by the JSON-RPC 2.0 specification:

Code	Name	Description
-32700	Parse error	Invalid JSON
-32600	Invalid request	Not a valid JSON-RPC request
-32601	Method not found	Unknown method name
-32602	Invalid params	Invalid method parameters
-32603	Internal error	Unspecified server error

AHP Application Codes

Code	Name	Description
-32001	SessionNotFound	The referenced session URI does not exist
-32002	ProviderNotFound	The requested agent provider is not registered
-32003	SessionAlreadyExists	A session with the given URI already exists
-32004	TurnInProgress	The operation requires no active turn, but one is in progress
-32005	UnsupportedProtocolVersion	The server cannot speak any of the protocol versions offered by the client in InitializeParams.protocolVersions. The data field of the JSON-RPC error MAY be an UnsupportedProtocolVersionErrorData advertising the protocol versions the server is willing to speak.
-32006	ContentNotFound	The requested content URI does not exist
-32007	AuthRequired	A command failed because the client has not authenticated for a required protected resource. The data field of the JSON-RPC error MUST be an AuthRequiredErrorData describing the resources that require authentication.
-32008	NotFound	The requested file, folder, or URI does not exist
-32009	PermissionDenied	The client is not permitted to access the requested resource. Servers SHOULD return this when a client attempts to read or browse a path outside the allowed set (e.g. outside the session's working directory or workspace roots). The data field of the JSON-RPC error MAY be a PermissionDeniedErrorData advertising a resourceRequest that, if granted, would unlock the operation.
-32010	AlreadyExists	The target resource already exists and the operation does not allow overwriting (e.g. resourceWrite with createOnly: true).
-32011	Conflict	An optimistic-concurrency precondition failed. Returned when a request carries a precondition token that no longer matches the receiver's current state — for example, resourceWrite with an ifMatch etag that has been superseded by a concurrent write. Callers SHOULD re-read the resource (e.g. via resourceResolve) and decide whether to retry the operation with the fresh token or surface the conflict to the user.

Error Response Format

All error responses follow the JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "No agent registered for provider 'unknown'",
    "data": {}
  }
}

The data field is OPTIONAL and MAY contain additional structured information about the error. Its shape is not defined by the protocol.

Typed Error Data

A handful of error codes carry a typed data payload. The mapping is captured by AhpErrorDetailsMap; the typed AhpError<C> union narrows data based on the code.

AuthRequiredErrorData

Details carried in the data field of an AuthRequired (-32007) error.

Wraps the protected resource list in { resources: [...] } rather than returning a bare array, so additional fields can be added in future versions without breaking the wire shape.

Field	Type	Description
resources	ProtectedResourceMetadata[]	Protected resources that require authentication.

PermissionDeniedErrorData

Details carried in the data field of a PermissionDenied (-32009) error.

The receiver MAY advertise a resourceRequest payload describing the access that, if granted, would unlock the operation. The caller MAY then issue resourceRequest with that payload to negotiate access.

Field	Type	Required	Description
request	ResourceRequestParams	No	The resource access that, if granted via resourceRequest, would unlock the operation. Omitted when no specific access grant would resolve the denial (for example, when the resource is fundamentally inaccessible).

UnsupportedProtocolVersionErrorData

Details carried in the data field of an UnsupportedProtocolVersion (-32005) error.

Field	Type	Description
supportedVersions	string[]	Protocol versions the server is willing to speak. Each entry is either a SemVer MAJOR.MINOR.PATCH string (e.g. "0.1.0") or a SemVer range constraint (e.g. ">=0.1.0 <0.3.0" or "^0.2.0").

AhpErrorDetailsMap

Maps each AHP error code that carries structured data to the type of that data.

Error codes not present in this map either have no data payload or carry an unspecified payload that callers SHOULD treat as unknown.

Field	Type	Description
[AhpErrorCodes.AuthRequired]	AuthRequiredErrorData
[AhpErrorCodes.PermissionDenied]	PermissionDeniedErrorData
[AhpErrorCodes.UnsupportedProtocolVersion]	UnsupportedProtocolVersionErrorData

AhpErrorCode

Union type of all AHP application error codes.

(typeof AhpErrorCodes)[keyof typeof AhpErrorCodes]

JsonRpcErrorCode

Union type of all JSON-RPC error codes.

(typeof JsonRpcErrorCodes)[keyof typeof JsonRpcErrorCodes]

AhpErrorCodeWithData

AHP error codes that carry a structured data payload.

keyof AhpErrorDetailsMap

AhpError

A typed JSON-RPC error object whose data is narrowed by code.

Distributes over the AhpErrorCode union so narrowing on code reveals the precise data type. For codes listed in {@link AhpErrorDetailsMap} data is required; for all other codes data is an optional unknown.

function handle(err: AhpError) {
  if (err.code === AhpErrorCodes.PermissionDenied) {
    err.data.request; // typed as ResourceRequestParams | undefined
  }
}

C extends AhpErrorCode ? C extends keyof AhpErrorDetailsMap ? { /** The error code. / readonly code: C; /* Human-readable error message. / readonly message: string; /* Structured detail payload mandated by [AhpErrorDetailsMap](#ahperrordetailsmap). / readonly data: AhpErrorDetailsMap[C]; } : { /* The error code. / readonly code: C; /* Human-readable error message. / readonly message: string; /* Optional, unspecified detail payload. */ readonly data?: unknown; } : never

Version Introduction

All error codes listed above were introduced in protocol version 1.