Skip to main content
First identify whether the failure belongs to an HTTP request, background Run, Tool call or local command. An accepted request may later fail or wait; HTTP success does not establish task success. The table is an actionable index of common errors, not a promise that every internal error string is a stable public code.

HTTP and SDK error format

This is an illustrative shape, not an execution log. The HTTP handler maps Zod validation failures to 400 invalid_request with field paths; ExecutionError preserves its status and error.code. Fastify client errors become invalid_http_request with the corresponding 4xx status, including oversized bodies. Unclassified failures become 500 internal_error without exposing database queries or upstream exceptions. Missing/invalid identity returns 401 unauthorized. Correct URL, Token and role rather than retrying permission failures. Tenant-scoped missing resources may return 404 without revealing that another tenant owns them. Both SDKs expose HexagonError.status and .code; ordinary HTTP errors without a structured code use http_error. They do not preserve the example’s fields array as an exception property. Network, timeout, JSON parsing and local discovery errors are not necessarily HexagonError. TypeScript stream-open failure uses event_stream_failed; Python truncated streams can raise ConnectionError. Do not assume every exception means the server rejected the operation. See Python and TypeScript.

Handle by phase

The HTTP column records the status at the corresponding ExecutionError branch. Background worker paths can record the same error on a Run/event rather than return it directly to the current caller. Source links identify actual branches, not fresh passing tests.

Errors that arrive inside successful responses

A successful HTTP response can report a failed operation. Connection validation catches remote verification failures and returns the connection with status: invalid, a scoped validation.code, and enabled: false; an SDK exception is not required. Re-check status before enabling. connection_changed_during_validation instead means the original version could not be updated because the configuration changed or disappeared while verification was running. Its remote verification request may already have happened. Similarly, Tool reconciliation returning state: completed means the result has been durably delivered. If the caller verified outcome: failed, the delivered Tool result contains an error; it does not mean the external write succeeded. Repeating an identical recorded resolution returns it, while incompatible replacement evidence produces tool_resolution_conflict. Inspect the resolution content, not just the outer state.

Preflight reasons are not retry instructions

Combination preflight returns compatibility.reasons, including incompatible_model, harness_tools_unsupported, sandbox_oci_image_unsupported, sandbox_private_image_unsupported, harness_initialization_unsupported, missing_capability, network_policy_unsupported and credential_proxy_not_allowed_by_network_policy. These describe incompatibility; they do not all imply the same HTTP response or a failed remote allocation. Correct the combination or explicitly revise requirements. Never silently replace an allowlist with unrestricted access.

Establish the original outcome before retrying

  • Query/event transport failure: bounded backoff, same Run and committed cursor; correct authentication first when applicable.
  • Lost Run submission response: recover with the same Session, input, origin and key; do not generate another key.
  • Lost Session/cloud creation response: preserve intent, identifiers and time; inspect original objects/operations. Do not assume Run submission idempotency applies.
  • Unknown Tool write: inspect call, request hash and pinned policy, then resolve only after checking upstream records; do not re-dispatch.
  • Unconfirmed close/delete: retain resource/deletion receipts and reconcile the original operation. Stopping the service or an empty list does not universally prove cleanup.
Resources may already exist and writes may already have happened. Neither internal_error nor client timeout guarantees no effects. Follow recovery and reconciliation.

Three recovery decisions

Submission timed out after the server accepted it. Keep the original Session ID, full input, origin and idempotency key in your durable request record. Resubmit that exact intent. The server returns the existing Run when its hash matches; changing the text or origin under the same key produces idempotency_conflict. A new key represents another submission and can duplicate work. See the durable backend example. A user clicks Approve after cancellation. A stale decision may return stale_approval; read the original approval and Run. Do not create a new approval to bypass the response. Repeating the already-recorded identical decision can return that record, which still does not prove the external operation ran. Inspect the Tool result and any cancellation-race outcome separately. The model produced output but export failed. The worker can settle the Run as failed with artifact_export_rejected, even after the Harness process ran. Query persisted artifacts and the original Run/events. Repeating the whole task could repeat file changes or external effects; diagnose the export failure before deciding whether a follow-up is appropriate. This worker code is recorded on the Run, not an HTTP status returned by the earlier successful submit.

Record an error without changing its meaning

A useful application error record contains the operation kind, request correlation ID, exception class, available HTTP status/code and whether a Run ID is already known. Keep full inputs, keys and resource references in private durable state as needed for recovery; omit them from public logs. The SDK’s exception message alone is not enough to select a retry policy. Use a separate outcome such as “submission outcome unknown” when a write loses its response. Do not label it “rejected” merely because the client threw an exception. For read-only event observation, reconnecting the same Run is appropriate; for resource creation or external writes, first inspect the original operation. A generic HTTP 409/500 handler cannot safely choose the same action for all these cases.

Unclassified errors and local commands

Record time, request method and sanitized path, HTTP status/code, business correlation ID and private Session/Run/operation references. Query durable Run, Tool call and resource-operation state, then export diagnostics. Exclude Authorization headers, credential-bearing preview URLs, original secrets and complete user inputs. The local launcher, dependency probes, provider SDKs and some Runtime failures still emit text or ordinary exceptions rather than a unified HTTP code. Follow CLI and the relevant integration guide; do not invent API codes for them. When implementation/evidence is inconclusive, retain the unknown state and distinguish observed facts from unverified conclusions. All 41 common-code table rows were matched to an actual code/status branch in their linked source files; see the branch review. This checks the documented index, not every internal string or runtime path. No new remote fault injection is claimed. Next: troubleshooting, limits, recovery.