Error Catalog

[AVAILABLE]. Every row below was triggered against a live server, not inferred from reading source alone. See Error handling for the envelope shape this table assumes.

Authentication

Status	Code	Message	Condition	What to do
401	none	`authentication required`	`Authorization` header missing, not a `Bearer <key>`, or the key doesn’t match a configured hash	Send a valid key from Authentication. Not retryable without fixing the header.

Authorization (caller is known; not permitted to act as this principal)

Status	Code	Message	Condition	Routes	What to do
403	none	`Caller is not permitted to assert this authority.principalId.`	`transaction.authority.principalId` is missing/empty, or doesn’t equal the authenticated `callerId` (default, no `allowedPrincipalIds` configured for this key), or isn’t present in that key’s configured `allowedPrincipalIds` list (`isPrincipalAllowed`, `packages/api/src/routes/execute.ts` / `transactions.ts`)	`POST /execute`, `POST /transactions`	Set `authority.principalId` to an identity this caller’s key is actually permitted to assert. Skipped entirely (no 403 possible) when caller authentication itself is disabled.

Policy denial (request well-formed; the business rule said no)

Status	Code	Message	Condition	Routes	What to do
403	`POLICY_DENIED`	`Execution rejected: <policy-specific reason>`	Policy evaluation returned `REJECTED` (`ExecutionGate.enforce`, `packages/runtime/src/ExecutionGate.ts`, thrown with an explicit `status: 403, code: "POLICY_DENIED"`)	`POST /execute`, `POST /transactions`	This is a real, observed pipeline outcome, not a bug: the request was well-formed but the business decision was no. Read the reason string; it names the specific Policy condition that failed. Distinct from the caller-identity 403 above — that one is about who the caller may act as, this one is about whether the requested action itself is allowed. Previously indistinguishable from a genuine server error (both surfaced as a generic `500`), now corrected.

Validation (caller’s request is malformed)

Status	Code	Message	Condition	Routes	What to do
400	none	`businessTransactionId must be a valid UUID.`	`businessTransactionId` present but not a valid UUID v1-v5	`POST /execute`, `POST /transactions`, `POST /verify`, `POST /receipt`	Fix the ID format. Not a transient failure.
400	none	`businessTransactionId is required.`	`businessTransactionId` missing entirely	`POST /replay`	Include the field. `/replay` checks presence only, not UUID format, unlike the routes above.
400	none	`authorization.authorityId must match authority.authorityId.`	A Business Transaction trust-chain invariant failed (`BusinessTransactionValidationError`)	`POST /execute`, `POST /transactions`	Fix the request body’s internal consistency; this is one example invariant among several the shared validator enforces.
400	none	`{"valid":false,"errors":["policyId is required."]}` / `["policyVersion is required."]`	`policyId` or `policyVersion` missing/empty, checked in that order, first miss short-circuits	`POST /policies/validate`	Supply both fields. This route never uses the shared `{error}` envelope, see Error handling.

Not found

Status	Code	Message	Condition	Routes	What to do
404	none	`Policy '<name>' version '<version>' was not found.`	`transaction.policy.name`/`version` doesn’t match any published Policy (`PolicyNotFoundError`)	`POST /execute`, `POST /transactions`	Publish the policy first, or fix the name/version in the request.
404	none	`{"valid":false,"errors":["Policy '<name>' version '<version>' was not found."]}`	Same condition as above, different envelope	`POST /policies/validate`	Same fix; this route reshapes the error locally instead of using the shared handler.
404	none	`Business Transaction not found.`	No Business Transaction exists for the path ID	`GET /transactions/{id}`	Confirm the ID; nothing to retry.
404	`VERIFICATION_FAILED`	`Execution Trust Record not found.`	No Execution Trust Record exists for `businessTransactionId` (`VerificationFailedError`, reused across three POST routes)	`POST /verify`, `POST /receipt`, `POST /replay`	Confirm the record exists via `GET /trust-records/{id}` first.
404	none	`Execution Trust Record not found.`	Same underlying condition, but reached via a GET, no `code` field on this path	`GET /verification/{id}`, `GET /receipt/latest/{id}`, `GET /trust-records/{id}`	Same fix; note the `code` field’s presence depends on which route you called, not on the underlying cause.
404	none	`Verification not found.`	Record exists but has no Verification yet	`GET /verification/{id}`	In practice every Execution produces a Verification synchronously, this is an edge case for records that haven’t completed that step.
404	none	`Receipt not found.`	Record exists but has no Receipt yet	`GET /receipt/latest/{id}`	Call `POST /receipt` first, or the record’s Execution hasn’t reached that stage.
404	none	`No authenticated caller identity available.`	No caller identity on the request, in practice only reachable when caller authentication is disabled (`PARMANA_AUTH_DISABLED=true`, local development only)	`GET /callers/me`	Not reachable under normal, authenticated operation. See Authentication.

Rate limited

Status	Code	Message	Condition	Routes	What to do
429	`RATE_LIMITED`	`Rate limit exceeded. Try again later.`	Caller (by authenticated identity, not IP) exceeded the configured `/execute` rate limit, or the caller’s IP exceeded the separate, more permissive `/health`/`/ready` limit	`POST /execute`, `GET /health`, `GET /ready`	Back off; the response carries a `Retry-After` header. Not a transient server issue — no nonce is consumed and nothing is signed for a request rejected here. See Authentication for the mechanism.

Conflict

Status	Code	Message	Condition	Routes	What to do
409	none	`Business Transaction '<id>' already exists.`	A Business Transaction with this `businessTransactionId` already exists (`DuplicateBusinessTransactionError`)	`POST /execute`, `POST /transactions`	This is not a transient failure to retry. Fetch the existing record instead, see Idempotency and nonces.
409	`RECEIPT_GENERATION_FAILED`	`Execution Trust Record must be successfully verified before a Receipt can be generated.`	The record exists but its latest Verification isn’t `VERIFIED`	`POST /receipt`	Call `POST /verify` first and confirm `status: VERIFIED` before requesting a Receipt.

Not listed here on purpose: NonceAlreadyConsumedError (409, code NONCE_ALREADY_CONSUMED) is a real, tested error error-handler.ts maps — thrown by ExecutionGateway.execute() when every other verification check passed and only nonce consumption failed (an isolated replay of an already-executed authorization). It is not reachable through any of the 15 routes this catalog covers: a resubmitted businessTransactionId is always caught first by the DuplicateBusinessTransactionError 409 above, before a second authorization — and thus a second nonce — is ever generated. It’s a library-level guarantee for a receiving system calling @parmana/execution-gateway directly, not an HTTP-reachable outcome of Parmana’s own server.

Server-side (500)

Status	Code	Message	Condition	Routes	What to do
500	none	`Internal Server Error`	A structurally incomplete but UUID-valid body (for example, `businessTransactionId` present but `metadata` missing) throws an unhandled `TypeError` inside `BusinessTransactionValidator.validate` before any typed error class is constructed	`POST /execute`, `POST /transactions`	Send every required nested object from the OpenAPI reference’s request schema. The generic message hides the real cause; it is visible only in server logs.
500	none	`Internal Server Error`	Known regression, not yet fixed: no Connector is registered for the request’s `action`. Previously reached the client as a coded `RuntimeError` (`"No connector registered for action: <action>.", code: RUNTIME_ERROR`); it no longer does, see Error handling for the mechanism.	`POST /execute`, `POST /transactions`	Use a registered `action`. Nothing is wired by default outside `NODE_ENV=test` (which registers `test:fixture-execute`); `hubspot:deal-update` registers only when its credentials are configured, see Connector Development Guide. This is a product regression to fix in `packages/connector-sdk`, not a documentation issue.

What’s deliberately not here

This catalog lists errors from the 15 routes in packages/api/src/app.ts. It does not cover exceptions raised only in code paths unreachable from the HTTP API (for example, internal validator classes that never escape a route handler uncaught), or client-side SDK exceptions, see Python SDK and TypeScript SDK for how each wraps these same HTTP responses.

Get Started

Core Concepts

Guides

SDKs

REST API

Security & Deployment

Integrations

Tutorials

Advanced

Support

Changelog

Authentication

Authorization (caller is known; not permitted to act as this principal)

Policy denial (request well-formed; the business rule said no)

Validation (caller’s request is malformed)

Not found

Rate limited

Conflict

Server-side (500)

What’s deliberately not here

​Authentication

​Authorization (caller is known; not permitted to act as this principal)

​Policy denial (request well-formed; the business rule said no)

​Validation (caller’s request is malformed)

​Not found

​Rate limited

​Conflict

​Server-side (500)

​What’s deliberately not here

Authentication

Authorization (caller is known; not permitted to act as this principal)

Policy denial (request well-formed; the business rule said no)

Validation (caller’s request is malformed)

Not found

Rate limited

Conflict

Server-side (500)

What’s deliberately not here