Errors

Unified Harness Protocol, version 2026-10-19

A client's error handling is only as good as the server's error reporting. This chapter defines one envelope, a closed set of codes, and which failures are worth retrying.

1. The error envelope

Every non-2xx response MUST have this body:

{
  "error": {
    "type": "invalid_request_error",
    "code": "harness_not_found",
    "message": "No harness with id 'chrn_deadbeef'.",
    "param": "metadata.harness_id",
    "detail": null
  }
}

Rules:

• message MUST be safe to show a user. It MUST NOT contain credentials, internal hostnames, file paths, or stack traces.
• code MUST come from §3 where one applies. A server MAY define additional codes for conditions this specification does not cover, and MUST namespace them with a vendor prefix (acme_…) so a future version of this specification cannot collide with them.
• A server MUST NOT return 200 with an error inside. The failure of a task is reported as a response with status: "failed" and HTTP 200, because the request succeeded; the failure of a request is a non-2xx with this envelope. Those are different events and MUST NOT be conflated.

Compatibility note. A server MAY additionally include a top-level detail string alongside error, for clients written against implementations that predate this envelope. That field is deprecated, carries no information not in error.message, and will be removed in a future version.

2. Error types

3. Error codes

3.1 Request and routing

model_not_available and model_unavailable are refused at different moments and are not interchangeable. model_not_available refuses a request that writes a harness (a create or update whose default_model its base does not run), before any task exists; model_unavailable refuses a task whose model cannot be served for its harness, when the task is sent. The first tells the client to fix the harness, the second to send the task with another model.

3.2 Authentication and limits

3.3 Execution

4. Retrying

Retries of POST /v1/responses MUST carry an Idempotency-Key. Without one, a retry after a timeout runs the task a second time — and the first may still be running, editing the same files. This is the single most damaging mistake a UHP client can make; see Tasks §6.

5. Timeouts

A client SHOULD set generous timeouts. Agent tasks routinely run for minutes; a 30-second HTTP timeout will cancel healthy work.

• Streaming: no total timeout. Use an inactivity timeout instead — a server SHOULD emit a comment line (: keep-alive) at least every 30 seconds so the client can distinguish a working agent from a dead connection.
• Non-streaming: at least the task's timeout_seconds, plus margin.
• A client that gives up MUST NOT assume the task stopped. It has not. Cancel it explicitly.