docs/api/03-error-model.md (“Error Model v1 (Locked)”) defines 24 canonical error codes across six categories. REST API → Error Model already documents that the running server doesn’t use this spec’s nested { "error": { "code", "message" } } shape at all — it returns a flat { "error": string }, with a top-level code attached only for errors that subclass packages/runtime/src/errors/RuntimeError.ts’s RuntimeError. This page goes one level further: of the 24 specified codes, which ones are actually thrown by any code in packages/, and do they reach an HTTP response?
The canonical list
| Category | Codes |
|---|---|
| Validation | INVALID_REQUEST, INVALID_METADATA, INVALID_POLICY, INVALID_SIGNALS, INVALID_SCHEMA |
| Authentication | UNAUTHENTICATED, INVALID_TOKEN, TOKEN_EXPIRED |
| Authorization | FORBIDDEN, INSUFFICIENT_PERMISSIONS |
| Resource | BUSINESS_TRANSACTION_NOT_FOUND, EXECUTION_NOT_FOUND, RECEIPT_NOT_FOUND, POLICY_NOT_FOUND, VERIFICATION_NOT_FOUND |
| Conflict | DUPLICATE_TRANSACTION, OVERRIDE_NOT_ALLOWED, IMMUTABLE_RESOURCE |
| Verification | VERIFICATION_FAILED, INVALID_SIGNATURE, TRUST_RECORD_CORRUPTED, POLICY_MISMATCH |
| Internal | INTERNAL_ERROR, STORAGE_FAILURE, UNEXPECTED_ERROR |
What’s actually wired up
Searchingpackages/ for each literal code string turns up exactly five that appear as the code value of a real, constructible error class — all the rest have no corresponding thrown error anywhere in the monorepo today.
| Code | Thrown by | Reaches an HTTP code field? |
|---|---|---|
VERIFICATION_FAILED | VerificationFailedError (packages/runtime/src/errors/VerificationFailedError.ts), thrown by VerificationService.verify() when the trust record doesn’t exist | Yes. It extends RuntimeError, so errorHandler’s instanceof RuntimeError branch attaches it: { "error": "...", "code": "VERIFICATION_FAILED" }, status 404. Reachable via POST /verify with an unknown businessTransactionId. |
POLICY_NOT_FOUND | PolicyNotFoundError in packages/shared/src/errors/policy-not-found-error.ts (code: "POLICY_NOT_FOUND", extends ParmanaError) | No. The PolicyNotFoundError actually thrown at runtime is a different class with the same name in packages/policy/src/errors/PolicyNotFoundError.ts, which has no code field at all — that’s the one FilePolicyRepository.load() throws and the one errorHandler imports and checks. The shared package’s version, with the real POLICY_NOT_FOUND code, is never thrown anywhere reachable. |
BUSINESS_TRANSACTION_NOT_FOUND | BusinessTransactionNotFoundError (packages/shared/src/errors/business-transaction-not-found-error.ts), thrown by ExecutionService.create() | No. This class extends ParmanaError, not RuntimeError, and errorHandler doesn’t have a specific instanceof check for it either — it falls through to the generic 500 { "error": "Internal Server Error" } branch, logged via console.error. A well-formed 404-shaped domain error becomes a generic 500 in the actual HTTP response. |
FORBIDDEN | ForbiddenError (packages/shared/src/errors/forbidden-error.ts) | Defined, but not observed to be thrown from any reachable path under packages/runtime or packages/api in this snapshot — there’s no authorization check anywhere yet to trigger it (see Authentication). |
OVERRIDE_NOT_ALLOWED | OverrideNotAllowedError (packages/shared/src/errors/override-not-allowed-error.ts) | Defined, but unreachable in practice: nothing under packages/api calls OverrideService at all (see Guides → Human Override), so nothing can trigger this. |
INSUFFICIENT_PERMISSIONS, EXECUTION_NOT_FOUND, RECEIPT_NOT_FOUND, VERIFICATION_NOT_FOUND, DUPLICATE_TRANSACTION, IMMUTABLE_RESOURCE, INVALID_SIGNATURE, TRUST_RECORD_CORRUPTED, POLICY_MISMATCH, INTERNAL_ERROR, STORAGE_FAILURE, UNEXPECTED_ERROR — do not appear as the code of any error class anywhere under packages/ in this snapshot. Failures that conceptually match several of these (missing businessTransactionId, a not-found trust record, a not-found receipt) are reported today as plain { "error": string } bodies with no code at all, directly from the route handler — see the practical status-mapping table in Error Model.
Related
Error Model
The full spec-vs-implementation breakdown this page builds on.
Glossary
Other normative vocabulary from the specification.
TypeScript SDK → Errors
A parallel, unrelated error hierarchy on the client side.
Verify
Where
VERIFICATION_FAILED is actually reachable.