VerdifaX

Errors

Every error response is JSON. Every error response has the same envelope. Stage failures get a 422 with the failing stage named explicitly.

Error envelope

{
  "ok": false,
  "duration_ms": 12,
  "duration_micros": 12450,
  "error": "human-readable message",
  "error_stage": "DOG"
}

error_stage is populated for phase-rejection or budget-halt responses. It can be one of the nine pipeline stage codes, or the governance phase code:

DOG  DTL  DKEC  AER  ZKSP  SEALING  LEDGER  REGISTRY  DLA  PEPG  CCV  MACC

Governance gates:

  • PEPG, Pre-Execution Policy Gate denied the request. Response includes a sealed deny_receipt. No execution occurred.
  • CCV, Continuous Constraint Verification detected a per-run budget breach mid-flight. Response includes a sealed ccv_halt_receipt with partial execution state.
  • MACC, Multi-Agent Coordination Constraint detected the tenant's cumulative budget was exceeded. Response includes a sealed macc_halt_receipt. No execution occurred.

Status codes

CodeWhenCaller action
200Request processed (may be denied by policy or budget halt)Check ok field and error_stage; fetch the sealed artifact if non-OK
400Malformed JSON, missing required field, bad hexFix the request
401Missing or invalid X-Verdifax-Key (only when keys exist)Provide a valid key
404Run id not found, or not visible to the caller's keyConfirm the id and the key
422A pipeline stage crashed (e.g., DOG, DTL, DKEC)Read error_stage; this is a stage_error, not a sealed outcome
429Rate limit exceeded (per-key)Retry after the Retry-After header
500Unhandled internal errorReport to the operator with the request id

Stage errors vs. sealed halt outcomes

Sealed halt outcomes (policy/budget decision, OK status, sealed artifact):

  • PEPG, A PSL rule fired with deny effect. Response status 200, ok: false, deny_receipt included.
  • CCV, Per-run budget breached mid-flight. Response status 200, ok: false, ccv_halt_receipt included, partial execution sealed.
  • MACC, Cumulative budget exceeded. Response status 200, ok: false, macc_halt_receipt included.

Stage errors (pipeline crash, HTTP 422, unsealed):

When a pipeline stage crashes (e.g., DOG envelope parsing fails, DKEC kernel crashes), the orchestrator persists the run with outcome_kind: "stage_error" and returns HTTP 422. The run is still visible in /runs and /runs/{id} for forensic review, failures are auditable, not silent.

curl -s -X POST http://localhost:9090/execute \
  -H "Content-Type: application/json" \
  -H "X-Verdifax-Key: vfx_..." \
  -d '{ "payload_text": "x", "program_id": "not-hex", ... }'

{
  "ok": false,
  "error": "program_id must be 64-char hex, got 7 chars"
}

No sealed artifact exists for stage_error runs. The run record itself is the only evidence, and it is not independently verifiable.

Continue