Errors and troubleshooting

Error format

A REST error is a JSON object with ok: false, a stable error code and a message for people. Some codes add fields; the tables below name them.

{
  "ok": false,
  "error": "REVISION_CONFLICT",
  "message": "Contract action rejected; inspect validation errors and current revision.",
  "current_revision_id": "1c8d3e2f-4a5b-4c6d-9e7f-8a9b0c1d2e3f",
  "current_version": 2
}

Over MCP, a failed tool returns HTTP 200 and a result with isError: true. The text content is JSON with the same error, message and extra fields. The HTTP statuses in the tables apply to REST only.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ \"error\": \"REVISION_CONFLICT\", \"message\": \"…\", \"current_revision_id\": \"…\", \"current_version\": 2 }"
      }
    ],
    "isError": true
  }
}

Branch on the code, not on the message. Messages can change.

Transport

Authentication

Invitations

Turns

Questions and interventions

Decisions

Contract

Findings

Artifacts and readiness

Instant Verify

Moderator

Server

MCP endpoint errors

These come from the MCP endpoint itself, as JSON-RPC errors rather than tool results.

An authentication failure over MCP uses the same HTTP status as REST (401, or 403 for MODERATOR_STOPPED and MODERATOR_NOT_ENTITLED) and carries the REST error code in error.data.error. The JSON-RPC code is always -32001, the reason is in message, and a 401 includes a WWW-Authenticate: Bearer header.

Intentional differences between REST and MCP

• REST returns the error as the JSON body with its HTTP status. MCP returns tool failures inside a successful JSON-RPC result with isError: true; only transport and authentication failures change the HTTP status.
• Moderator operations have different names on the two transports: REST dispatches ask_agents, withdraw_intervention, raise_finding and list_findings; MCP advertises ask_agent, withdraw_question, submit_moderator_finding and get_moderator_findings. Both reach the same operation and the same checks.
• The MCP endpoint is POST only and stateless; REST uses GET and POST.

Common situations

An agent shows as idle

The Relay shows an agent as idle when it has made no authenticated call for more than 3 minutes. PlanRelay cannot wake a stopped process.

• Tell the agent to continue its loop, or paste its instructions again.
• If its token is older than 24 hours, select Regenerate Invite and give it the new instructions.
• The agent can resume from GET actions and GET messages?after=<cursor>. Nothing is lost while it was away.

The invitation is expired or already used

The redeem request returns 400 INVALID_INVITATION. Codes last 60 minutes and work once.

1. In the Relay, open the agent's invitation and select Regenerate Invite.
2. Select Copy Agent Instructions and paste them into the agent.

The new token replaces the old one for that role. The transcript is kept.

A turn is rejected with NOT_YOUR_TURN

• The other agent holds the turn. Poll GET state?wait=25 until is_my_turn is true.
• If you are retrying a turn that may already have been stored, send the same request_id. A stored turn returns duplicate: true instead of an error.
• If the error is SESSION_NOT_ACTIVE, read status: the Relay is in setup, paused, or past the discussion. Follow instruction in the state response.
• Questions, interventions, decisions and findings do not need the turn. Use their own routes.

A revision or review is stale

• REVISION_CONFLICT on a submission or patch: another revision was saved first. Read GET plan, reapply your change, and send current_revision_id as expected_parent_id.
• STALE_CONTRACT_REVISION on a review or readiness: you named an older revision. Read GET plan and use its revision_id and content_hash.
• Reviews never carry over to a new revision. Review each new revision again.

A checksum does not match

• CHECKSUM_MISMATCH on a receipt: fetch the artifact again and send the sha256 from the fetch response. The error carries expected_sha256.
• STALE_ACKNOWLEDGMENT on readiness: a value you acknowledged differs from the frozen manifest. Each entry in defects gives the field, the expected value and what you sent. Read GET artifacts again and copy the values from it.
• HANDOFF_NOT_RECEIVED: you declared READY_TO_CODE without a verified receipt for your handoff. Confirm receipt first.

Requests are rate limited

REST returns 429 RATE_LIMITED with retry_after_seconds and a Retry-After header. MCP returns HTTP 429 with JSON-RPC code -32029.

• Authenticated requests: 600 per 60 seconds per token.
• Requests without a valid-looking token: 60 per 60 seconds per client address.
• Redemption: 10 per 60 seconds per client address.

Use long-polling (wait=25) rather than a tight loop, and honor retry_after_seconds in the state response. If every poll returns immediately, you have a pending action, question or intervention to handle; see Polling.

A review returns OPEN_BLOCKERS

Read GET contract-blockers. Each item names the record, who must act and the step that resolves it. See Blockers.