Standard Result and Error Contracts for Harness AI

Every response the harness emits to an external caller — Astro UI, n8n webhook, Telegram channel, or any other consumer — uses one of two contracts: the standard result for successful and approval-pending executions, and the standard error for any execution that terminates with a controlled failure. Both contracts share the execution_id field so callers can always correlate a response with its originating event and its audit trail.

Standard Result

Returned when an execution completes successfully or when it has been paused to await human approval.

JSON Schema

{
  "execution_id": "uuid",
  "status": "completed | failed | waiting_approval",
  "result": {},
  "sources": [],
  "warnings": [],
  "audit_ref": "uuid"
}

Fields

execution_id

UUID

required

Unique identifier of the execution. Generated when the originating event is created (see Execution Event Contract). Stable across all state transitions for the same execution.

status

enum

required

Final state of the execution at the time this response was produced.

Value	Meaning
`completed`	Execution finished successfully. Terminal state.
`failed`	Execution ended with a controlled error. Terminal state — see Standard Error below.
`waiting_approval`	Execution is paused pending human approval (triggered by `risk_level=high`). Transitions to `completed` on approval or `failed` on rejection.

result

object

required

The agent’s output. Shape is free-form and intent-specific. This field never contains full document content, PII outside the user’s authorized scope, internal tokens, private keys, internal paths, or stack traces.

sources

array

required

List of sources consulted during the execution — SQL views, documents, MCP responses, etc. Each element has the shape {type, id, ref, hash?}. Always present, even when empty ([]). An empty array must be returned explicitly so the client can render “no sources” rather than treating a missing field as an error.

warnings

array

required

Non-fatal conditions encountered during execution, such as approaching rate limits, partial data results, or restrictive policy constraints that were satisfied but noteworthy. Each element has the shape {code, message, severity}. Always present, even when empty.

audit_ref

UUID

required

ID of the first audit_events row associated with this execution. Clients can use this to navigate directly to the audit log. This field is never null — if no audit event was written, the execution cannot complete.

Status Transition Table

From	To	Trigger
`waiting_approval`	`completed`	Authorized approver accepts the action.
`waiting_approval`	`failed`	Authorized approver rejects the action (`APPROVAL_REJECTED`).
`completed`	(none)	Terminal state.
`failed`	(none)	Terminal state.

When status is waiting_approval, the response body will include an approval_id field alongside the standard fields. This ID is used to identify the pending approval request — for example, when an operator calls /rechazar (reject) or the equivalent UI action. The 202 Accepted HTTP status code is returned in this case rather than 200 OK.

The triplet execution_id + audit_ref + sources is sufficient to reconstruct the full execution from the UI or from an audit review. All three are required fields for exactly this reason.

Standard Error

Returned when an execution terminates with a controlled failure. This contract guarantees that no internal architecture details leak to the caller — error messages come from a pre-approved institutional catalog.

JSON Schema

{
  "execution_id": "uuid",
  "status": "failed",
  "error": {
    "code": "POLICY_DENIED",
    "message": "La política institucional bloqueó la acción solicitada.",
    "details": {}
  }
}

Fields

execution_id

UUID

required

Same ID as the originating event. Always present so callers can correlate the failure with the audit_events log.

status

string

required

Always "failed" for this contract.

error

object

required

Show error fields

error.code

enum

required

A controlled error code from the catalog below. Never a free-form string.

error.message

string

required

An institutional pre-approved message. Never concatenated with user input, stack traces, internal paths, framework traces, container IDs, environment variable names, or raw SQL table names.

error.details

object

required

Structured, safe supplementary data — for example {risk_level, policy_id, next_action}. Never contains stack traces, internal paths, variable names, or raw framework output.

Error Code Catalog

Code	Meaning	When emitted
`POLICY_DENIED`	The institutional policy blocked the requested action.	Policy engine rejects the `intent` or the `risk_level` cannot be satisfied.
`IDENTITY_NOT_FOUND`	The actor’s identity could not be resolved.	`mcp-identity-connector.get_user_context()` returns without a valid mapping.
`TOOL_NOT_ALLOWED`	The requested tool is not in the agent’s or actor’s allowlist.	Agent requests a tool outside its registered profile.
`RATE_LIMIT_EXCEEDED`	The per-user, per-command, or per-window rate limit was exceeded.	Redis rate limiter responds `throttled`.
`VALIDATION_FAILED`	The payload did not pass schema validation.	Pydantic v2 (runtime) or Zod (BFF) rejects the input.
`INTERNAL_ERROR`	An unexpected harness error occurred.	Any unclassified `500`-class failure. `details` is omitted; the stack trace is written only to `audit_events`.
`APPROVAL_REJECTED`	An authorized approver rejected the action.	Approver calls `/rechazar` or the equivalent UI action.
`TIMEOUT`	The tool or model exceeded its configured timeout.	Configured `timeout_ms` elapsed before a response arrived.

Security Guarantees

error.message is selected from the pre-approved institutional catalog — it is never dynamically composed from user input. This prevents information leakage through error messages regardless of what data the user supplied.

Every error is recorded in audit_events with event_type=execution.failed and the error_code populated. In external channels (Telegram, n8n), error.details is filtered further — only error.code and error.message travel to non-institutional actors. The full details object is available only to operators via the audit log.

Comparison: Result vs. Error

Field	Standard Result	Standard Error
`status`	`completed` or `waiting_approval`	Always `failed`
`result`	Agent output object	Absent
`sources`	List of sources used	Absent
`warnings`	Non-fatal warnings	Absent
`audit_ref`	Explicit UUID	Implicit via `execution_id`
`error`	Absent	Present with `code`, `message`, `details`

Contracts

Internal Endpoints

Standard Result and Error Contracts for Harness AI

Standard Result

JSON Schema

Fields

Status Transition Table

Standard Error

JSON Schema

Fields

Error Code Catalog

Security Guarantees

Comparison: Result vs. Error

Build docs developers (and LLMs) love

Contracts

Internal Endpoints

Documentation Index

​Standard Result

​JSON Schema

​Fields

​Status Transition Table

​Standard Error

​JSON Schema

​Fields

​Error Code Catalog

​Security Guarantees

​Comparison: Result vs. Error

Build docs developers (and LLMs) love

Standard Result

JSON Schema

Fields

Status Transition Table

Standard Error

JSON Schema

Fields

Error Code Catalog

Security Guarantees

Comparison: Result vs. Error