Error Catalog

Every error this API can return: HTTP status, code (when present), the exact condition that produces it, and what a caller should do. Assembled from live-triggered captures, not inferred from code.

[AVAILABLE]. Every row below was triggered against a live server this session or a previous session that produced REST API Introduction or the TypeScript SDK fix pass, 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) — corrected, see docs/CLAIMS.md §2.21.

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.

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 14 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. See docs/CLAIMS.md §2.21 for the exact scope.

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	Regression, verified in an earlier pass, 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); razorpay:refund-create and hubspot:deal-update register only when their respective credentials are configured, see Connector Development Guide. This is flagged as a product regression to fix in packages/connector-sdk, not a documentation issue.

What’s deliberately not here

This catalog lists errors from the 14 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.