Errors and recovery

Agents should treat errors as typed workflow outcomes, not as invitations to guess another project or endpoint.

Error	Meaning	Correct response
authentication required	No usable credential reached the server	Reconnect or authenticate; do not write
task not found	The task is absent from the authenticated project	Stop; do not recreate it
write_context_required	A mutation omitted the binding context	Rediscover the schema and provide the selected profile
resource_mismatch	The selected resource is not the address this connection uses (for example the shared /mcp sent on a per-project connection)	Stop and fix the connection profile
project_admin_required	project_update was called by a credential that is not a project owner or admin	Ask the project owner; do not retry
instance_mismatch	The request targets another instance	Stop and reconnect to the intended instance
project_mismatch	The request targets another project	Stop; do not switch projects silently
version_conflict	Another session changed the task first	Re-read and reassess the work
bridge_payload_too_large	A Bridge HTTP request body exceeded the 64 KiB application limit	Stop; send only the documented bounded payload
invalid_content_length	A Bridge HTTP request declared an invalid body length	Fix the client request framing; do not retry unchanged
completion_handoff_required	A new transition to done omitted handoff_completed or handoff_next	Keep the task open and submit a truthful handoff
completion_receipt_required	A new transition to done omitted the work receipt	Keep the task open and retry only after the work evidence is ready
idempotency_conflict	A retry key was reused with different input	Use a new logical operation or correct the payload
duplicate_work_receipt	The session receipt already exists	Re-read the task; do not append a duplicate

Bridge enrollment uses a separate HTTP error envelope:

{"error":{"code":"stable_machine_code","message":"short explanation"}}

Its authentication and lifecycle codes include bridge_enrollment_credential_invalid, bridge_enrollment_credential_expired, bridge_enrollment_credential_used, bridge_enrollment_credential_revoked, enrollment_challenge_not_found, enrollment_challenge_mismatch, enrollment_challenge_expired, enrollment_challenge_consumed, enrollment_proof_invalid, enrollment_key_mismatch, bridge_not_pending, bridge_identity_conflict, bridge_persistence_error, bridge_token_invalid, bridge_token_expired, bridge_token_revoked, bridge_token_pending, bridge_token_still_active, bridge_rotation_protocol_upgrade_required, bridge_rotation_in_progress, bridge_rotation_not_found, bridge_rotation_expired, bridge_rotation_aborted, bridge_rotation_confirmed, bridge_rotation_invalid_state, bridge_rotation_predecessor_revoked, bridge_rotation_predecessor_expired, bridge_revoked, idempotency_key_required, and idempotency_conflict. See the Bridge enrollment contract for request authentication and recovery behavior.

Task-version execution additionally rejects dispatch with bridge_offline and bridge_device_binding_mismatch when the heartbeat node key does not match its enrolled identity. Pairing also returns bridge_device_binding_mismatch when the submitted public key differs from the pending/active enrolled device's key. An unused owner-issued pairing code and the matching key allow initial pairing and re-pairing; rejection leaves the code and credentials unchanged. Task-reference dispatch also returns bridge_offline (no fresh heartbeat), bridge_upgrade_required (missing task-version-execution-v1 capability), or instance_identity_unconfigured (server identity missing). A Bridge claim also returns bridge_upgrade_required when the offered plan was built for a capability the Mac no longer reports; the offer stays offered. bridge_at_capacity means the Mac already has as many offered or running executions as it reports it can run (capacity per Mac); nothing was created, so dispatch again when a task finishes. task_time_limit_exceeded cancels an expired offer and blocks the workflow. RESULT rejects invalid_idempotency_key, and invalid_execution_result names the broken rule after the colon (title must start with RESULT; body must be 1-100000 characters and not only whitespace), invalid_receipt rejects a blank receipt.harness, and execution_result_rejected_by_storage means storage refused the RESULT or receipt and nothing was saved; verifier credentials cannot write RESULT (insufficient_scope: execution:result: verifiers report through the workflow verdict, not task_result, with a second execution_result_requires_worker guard at the mutation boundary). Every task_result call writes one audit_events row (operation=task_result, target the task, actor execution:<id>), succeeded or rejected with the error code (invalid_execution_result:title or :body for the two rules, invalid_receipt:harness, and invalid_arguments for an authenticated call the input schema refused), never the title, body, receipt or other argument values. Unauthenticated calls are not audited.

Never log authorization headers, tokens, database URLs, or full memory bodies while diagnosing a failed client.