HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.
Errors
Unified Harness Protocol, version 2026-09-12
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
}
}
| Field | Type | Required | Meaning |
|---|---|---|---|
type |
string | yes | Broad class; see §2 |
code |
string | yes | Specific, machine-readable reason; see §3 |
message |
string | yes | Human-readable, one sentence, no stack trace |
param |
string | null | yes | Dotted path to the offending field, when there is one |
detail |
object | null | yes | Structured extra context, or null |
Rules:
messageMUST be safe to show a user. It MUST NOT contain credentials, internal hostnames, file paths, or stack traces.codeMUST 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
200with an error inside. The failure of a task is reported as a response withstatus: "failed"and HTTP200, 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
detailstring alongsideerror, for clients written against implementations that predate this envelope. That field is deprecated, carries no information not inerror.message, and will be removed in a future version.
2. Error types
type |
HTTP | Meaning |
|---|---|---|
invalid_request_error |
400, 404, 409, 413, 422 | The request was wrong. Retrying it unchanged will fail again. |
authentication_error |
401 | The credential is missing, malformed or unknown. |
permission_error |
403 | Authenticated, but not allowed to do this. |
rate_limit_error |
429 | Too many requests, or a quota is exhausted. |
harness_error |
200 (in a failed response) | The harness ran and failed. |
server_error |
500, 502, 503, 504 | The server failed. Retrying MAY succeed. |
3. Error codes
3.1 Request and routing
| Code | HTTP | Meaning |
|---|---|---|
unsupported_protocol_version |
400 | UHP-Version names a version this server cannot serve. detail.supported lists what it can. |
invalid_input |
400 | The body could not be parsed, or a field has the wrong type. |
harness_not_found |
404 | No such harness in the caller's scope. |
response_not_found |
404 | No such response in the caller's scope. |
session_not_found |
404 | No such session in the caller's scope. |
plugin_not_found |
404 | The harness has no plugin of that name. |
file_not_found |
404 | No such file in the caller's scope. |
session_expired |
404 | The session existed but is past its retention. |
harness_mismatch |
409 | The task named a different harness than the session it continues. |
session_busy |
409 | A task is already running in this session. |
plugin_conflict |
409 | Two plugins share a name, or a component name collides across the harness and its plugins. detail.component, detail.name and detail.between say which. |
file_too_large |
413 | The upload exceeds the server's limit. detail.max_bytes states it. |
model_unavailable |
422 | The requested model cannot be served for this harness. |
unsupported_base |
422 | The requested harness base is not supported by this server. |
plugin_invalid |
422 | The package is not a valid Agent Plugins package: no manifest, a fatal manifest error, a path that escapes the root, or a name that contradicts the manifest. detail.path and detail.reason say where. |
unsupported_plugin_schema |
422 | The manifest's $schema names an Agent Plugins version this server does not install. detail.supported lists what it does. |
unsupported_transport |
422 | A plugin declares an MCP server whose transport cannot be run for this harness base. detail.transport and detail.base say which. |
3.2 Authentication and limits
| Code | HTTP | Meaning |
|---|---|---|
missing_credential |
401 | No bearer token. |
invalid_credential |
401 | The token is malformed, unknown, or revoked. |
insufficient_scope |
403 | The credential cannot perform this operation. |
rate_limited |
429 | Slow down. Retry-After SHOULD be set. |
quota_exhausted |
429 | A budget is spent; retrying now will not help. |
3.3 Execution
| Code | Where | Meaning |
|---|---|---|
harness_error |
failed response | The harness ran and could not complete the work. |
harness_unavailable |
503 | No capacity to run this harness right now. |
provider_error |
failed response | The upstream model provider refused or failed. |
timeout |
failed response | The task exceeded its wall-clock budget. |
cancelled |
cancelled response | The client cancelled it. |
preview_unavailable |
501 | This server does not render previews. |
preview_failed |
502 | Conversion of this file failed. |
4. Retrying
| Situation | Retry? |
|---|---|
server_error (500, 502, 503, 504) |
Yes, with exponential backoff and jitter |
rate_limited |
Yes, after Retry-After |
quota_exhausted |
No — nothing will change until the quota does |
session_busy |
Yes, once the in-flight task is terminal |
Any invalid_request_error |
No — fix the request |
authentication_error |
No — fix the credential |
A task that reached failed |
Only with the client's own judgment; it consumed real resources |
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.