Error Codes

Overview

PCP uses JSON-RPC 2.0 error codes extended with protocol-specific values in the -32000 to -32099 range. Every error response includes a numeric code, a human-readable message, and an optional data field with context about what went wrong.

Errors fall into two groups: standard JSON-RPC errors (parse and request problems) and PCP-specific errors (capability, permission, and execution failures). This page covers both.

Standard JSON-RPC Errors

These codes are defined by the JSON-RPC 2.0 specification and apply to any message sent over the PCP wire protocol.

Code	Name	Description	Recoverable?	Retry Strategy
-32700	PARSE_ERROR	Invalid JSON received by the server. The request body could not be parsed.	Yes	Fix the JSON and resend. Do not retry the same payload.
-32600	INVALID_REQUEST	The JSON is valid but not a conforming Request object. Missing required fields, wrong types, or structural issues.	Yes	Fix the request structure. Do not retry the same payload.
-32601	METHOD_NOT_FOUND	The requested method does not exist or is not available in the current PCP version.	No	Check the method name and PCP version. No retry.
-32602	INVALID_PARAMS	One or more parameters in the request are invalid. Wrong type, missing required field, or value out of range.	Yes	Fix the parameters and resend.
-32603	INTERNAL_ERROR	An unexpected internal error occurred in PCP Core. This is a bug, not a client error.	Maybe	Retry once after a short delay. If it recurs, log and escalate.

PCP-Specific Errors

These codes cover capability resolution, permission enforcement, execution failures, and adapter-level problems.

Discovery and Resolution

Code	Name	Description	Recoverable?	Retry Strategy
-32000	APP_NOT_FOUND	The application with the specified ID is not running or registered.	Yes	Wait for the app to start, or check if the ID is correct. Retry after polling app state.
-32001	SURFACE_NOT_FOUND	The surface with the specified ID does not exist. May have been closed between intent classification and execution.	Yes	Re-query the app’s surface tree and retry with a current surface ID.
-32002	ELEMENT_NOT_FOUND	The accessibility element with the specified ID no longer exists. The UI may have changed.	Yes	Re-query the element tree and retry with a current element ID.
-32015	CAPABILITY_NOT_FOUND	The requested capability does not exist for the target app. The app either does not declare it or has not registered it.	No	Check the capability manifest. The capability must be declared and active before invocation.

Permission and Confirmation

Code	Name	Description	Recoverable?	Retry Strategy
-32004	PERMISSION_DENIED	The requester does not have permission for this action. The action’s trust level exceeds what is allowed for this context.	Maybe	Request elevated permission or change the permission policy. Do not blindly retry.
-32005	CONFIRMATION_REQUIRED	The action requires user confirmation before execution. This is not an error in the traditional sense; it is a pipeline gate.	Yes	Present the confirmation prompt and wait for user response.
-32006	CONFIRMATION_DENIED	The user explicitly denied the confirmation request.	Yes	Respect the denial. Do not retry automatically. Ask the user if they want to try a different action.
-32007	CONFIRMATION_EXPIRED	The confirmation window timed out without a user response. The action was not executed.	Yes	Re-present the confirmation prompt if the intent is still relevant.

Execution Failures

Code	Name	Description	Recoverable?	Retry Strategy
-32003	ACTION_NOT_SUPPORTED	The requested action is not supported by the target element. The element type cannot perform this operation.	No	Check which actions the element supports. No retry with the same action.
-32008	TARGET_AMBIGUOUS	Target resolution returned multiple candidates with similar confidence scores. PCP cannot determine which one the user intended.	Yes	Present the candidates to the user for disambiguation. Retry with the user’s selection.
-32009	EXECUTION_TIMEOUT	The action did not complete within the configured timeout period. The app may be slow, frozen, or the operation may be genuinely long-running.	Maybe	Retry once. If it recurs, check app health before further attempts.
-32010	APP_UNRESPONSIVE	The target application is not responding to PCP requests. It may be frozen, crashed, or in a degraded state.	Maybe	Wait and retry. If the app remains unresponsive, suggest the user restart it.
-32011	NO_ATSPI2_SUPPORT	AT-SPI2 is not available for this element or application. The app may not have an accessibility tree, or the AT-SPI2 bus may be down.	Maybe	Check if the app supports accessibility. If the bus is down, wait for recovery.
-32012	INPUT_SIMULATION_FAILED	Tier 3 input simulation was attempted but failed. The compositor could not inject the input event.	Maybe	Retry once. If it fails again, the surface may have changed or input injection may be blocked.

Manifest and Security

Code	Name	Description	Recoverable?	Retry Strategy
-32016	MANIFEST_INVALID	A capability manifest failed structural validation. Missing fields, wrong types, or schema violations.	Yes	Fix the manifest and re-register. Do not retry with the same manifest.
-32017	MANIFEST_SIGNATURE_INVALID	The Ed25519 signature on a capability manifest could not be verified. The signing key may be untrusted or the manifest may have been tampered with.	No	Check the signing key and signature. Re-sign with a trusted key.
-32018	RATE_LIMITED	Too many requests in a short window. The rate limiter has throttled the caller.	Yes	Back off and retry after the rate limit window expires. Exponential backoff recommended.

Platform and Content

Code	Name	Description	Recoverable?	Retry Strategy
-32019	CAPTURE_FAILED	Screen capture failed. The target surface may not be available, or the compositor may have denied the capture request.	Maybe	Check that the surface still exists and the caller has capture permission. Retry once.
-32020	TEXT_TOO_LARGE	The requested text range exceeds the maximum size for a single request.	Yes	Split the request into smaller ranges and retry with pagination.
-32025	WINE_BRIDGE_ERROR	The Wine accessibility bridge (Tier 2b) reported an error. The Windows application’s accessibility layer may not be responding.	Maybe	Check the Wine bridge status and the Windows app’s accessibility support. Retry after a delay.

Error Response Format

All errors follow the JSON-RPC 2.0 error response structure:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32008,
    "message": "TARGET_AMBIGUOUS: multiple candidates found for 'open mail'",
    "data": {
      "candidates": [
        { "app_id": "org.example.thunderbird", "confidence": 0.92 },
        { "app_id": "com.example.geary", "confidence": 0.89 }
      ]
    }
  }
}

The data field is optional. When present, it provides additional context that varies by error code. Ambiguous target errors include the candidate list, permission errors include the required trust level, and timeout errors include the timeout duration.

Retry Guidelines

Not all errors should be retried automatically. The table above marks each code as recoverable or not. When retrying, follow these rules:

1. Never retry parse errors or invalid requests. The payload itself is broken; retrying with the same bytes will produce the same result.
2. Respect confirmation denials. If the user said no, do not retry the same action automatically.
3. Use exponential backoff for rate limits. Start with 1 second, double on each failure, cap at 30 seconds.
4. Re-query state before retrying stale references. If an element or surface was not found, fetch a fresh tree before retrying. The UI may have changed between the original request and the retry.
5. Stop after three consecutive failures. If the same request fails three times with an execution error, stop and report to the user rather than looping indefinitely.

Transaction Timeouts

Multi-step transactions (see the Execution Pipeline documentation) have their own timeout semantics. If a transaction step fails with EXECUTION_TIMEOUT, the entire transaction enters a rollback state. The rollback itself has a separate timeout. If rollback also fails, the transaction is marked as ABANDONED and logged to the audit trail with full context.