packages/*/src (its code and HTTP status), and each code in a real captured response in openapi/openapi.bundled.yaml. An error body is { "error": "<message>", "code": "<CODE>" }; a few refusals carry more fields, shown on the operation’s page. “Returned by” lists the operations whose documented responses name the code; an empty cell means the code can be returned by any operation that reaches that part of the server. What to do for each class of error: Errors and troubleshooting.
| Code | HTTP | Returned by | Example message | Declared in |
|---|---|---|---|---|
APPROVAL_ISSUER_CHANGE_NOT_FOUND | 404 | approveApprovalIssuerChange, rejectApprovalIssuerChange | Approver change ‘00000000-0000-0000-0000-000000000000’ not found. | packages/shared/src/errors/approval-issuer-change-not-found-error.ts |
AUDIT_UNAVAILABLE | 503 | packages/api/src/auth/AuditUnavailableError.ts | ||
AUTHORITY_GRANT_CHANGE_NOT_FOUND | 404 | approveAuthorityGrantChange, rejectAuthorityGrantChange | Authority grant change ‘00000000-0000-0000-0000-000000000000’ not found. | packages/shared/src/errors/authority-grant-change-not-found-error.ts |
AUTHORITY_REQUIRED | 400 | packages/shared/src/errors/authority-required-error.ts | ||
AUTHORITY_SELF_GRANT_DENIED | 403 | approveAuthorityGrantChange, proposeAuthorityGrantChange, rejectAuthorityGrantChange | ’grant-maker’ may not propose, approve or reject authority for itself. | packages/api/src/routes/authority-grants.ts |
AUTHORIZATION_NO_LONGER_VALID | 409 | executeTransaction | Not released: what the authorization for business transaction ‘38dcf000-99ed-43af-8666-46c63c8ada74’ rests on no longer holds (authority grant 9f3cf733-a8ed-487c-bb58-a53950388cdf is no longer the active grant of “warehouse-agent” for “erp:release-goods” (revoked or replaced)). Nothing was executed. Send a new request to be decided again. | packages/shared/src/errors/authorization-no-longer-valid-error.ts |
AUTHORIZATION_REQUIRED | 400 | packages/shared/src/errors/authorization-required-error.ts | ||
BUSINESS_SIGNAL_SOURCE_CHANGE_NOT_FOUND | 404 | approveBusinessSignalSourceChange, rejectBusinessSignalSourceChange | Business signal source change ‘00000000-0000-0000-0000-000000000000’ not found. | packages/shared/src/errors/business-signal-source-change-not-found-error.ts |
BUSINESS_TRANSACTION_NOT_FOUND | 404 | packages/shared/src/errors/business-transaction-not-found-error.ts | ||
CAPABILITY_NOT_ALLOWED | 403 | createTransaction, executeTransaction, getPolicyInEffect | Caller is not permitted to invoke this capability. | packages/api/src/routes/execute.ts |
CAPABILITY_NOT_BOUND | 404 | getPolicyInEffect | No policy is bound to capability “test:fixture-execute”. | packages/api/src/routes/policy-in-effect.ts |
CHALLENGE_RECORD_NOT_FOUND | 404 | packages/shared/src/errors/challenge-record-not-found-error.ts | ||
CONFLICT | 409 | approveApprovalIssuerChange, approveAuthorityGrantChange, approveBusinessSignalSourceChange, approveExternalConnectorChange, proposeApprovalIssuerChange, proposeAuthorityGrantChange, proposeBusinessSignalSourceChange, proposeExternalConnectorChange, rejectApprovalIssuerChange, rejectAuthorityGrantChange, rejectBusinessSignalSourceChange, rejectExternalConnectorChange | Approver ‘manager-priya’ key ‘manager-priya-key-1’ already exists. Use a new key id to add a new key. | |
CONNECTOR_NOT_REGISTERED | 503 | packages/shared/src/errors/connector-not-registered-error.ts | ||
DECISION_NOT_APPROVED | 400 | packages/shared/src/errors/decision-not-approved-error.ts | ||
DUPLICATE_BUSINESS_TRANSACTION | 409 | packages/shared/src/errors/duplicate-business-transaction-error.ts | ||
EXECUTION_INTENT_NOT_FOUND | 404 | finalizeExecutionIntent, resolveExecutionIntent | No Execution Intent exists for business transaction ‘unknown-transaction’. Transactions created before Execution Intents were introduced have none. | packages/runtime/src/errors/ExecutionIntentNotFoundError.ts |
EXECUTION_INTENT_NOT_RESOLVABLE | 409 | resolveExecutionIntent | The Execution Intent for business transaction ‘b1237ce3-305a-4004-8179-749352fc1ade’ is in state RELEASED and cannot be resolved by hand. Its execution result was saved, so rebuild the signed Trust Record with finalize instead. Nothing was changed. | packages/runtime/src/errors/ExecutionIntentNotResolvableError.ts |
EXECUTION_INTENT_RESOLUTION_INVALID | 400 | resolveExecutionIntent | The resolution is invalid: note is required. Record what you found at the connector. | packages/runtime/src/errors/ExecutionIntentResolutionInvalidError.ts |
EXECUTION_INTENT_RESULT_NOT_RECORDED | 409 | finalizeExecutionIntent | The Execution Intent for business transaction ‘b1237ce3-305a-4004-8179-749352fc1ade’ is in state PREPARED and has no saved execution result, so its signed Execution Trust Record cannot be rebuilt. The action may or may not have been released. Establish the outcome from the connector and reconcile it by hand. Nothing was called. | packages/runtime/src/errors/ExecutionIntentNotFinalizableError.ts |
EXECUTION_INTENT_UNAVAILABLE | 503 | packages/runtime/src/errors/ExecutionIntentUnavailableError.ts | ||
EXECUTION_INTENTS_NOT_ENABLED | 501 | finalizeExecutionIntent, resolveExecutionIntent | Execution Intents are not enabled on this deployment. | |
EXECUTION_OUTCOME_UNKNOWN | 502 | createTransaction, executeTransaction | The action for business transaction ‘38dcf000-99ed-43af-8666-46c63c8ada74’ was released to the execution system, but the call failed, so whether it was performed is unknown. Do not retry as a new transaction: check the target system, then close the Execution Intent with POST /execution-intents/38dcf000-99ed-43af-8666-46c63c8ada74/resolve. authorizationId: 4d291c90-9e93-4a8a-b214-8cc6526fe2e3. | packages/runtime/src/errors/ExecutionOutcomeUnknownError.ts |
EXECUTION_RECORD_INCOMPLETE | 500 | createTransaction, executeTransaction | The action for business transaction ‘e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a’ was released to the execution system, but its signed Execution Trust Record could not be produced. Do not retry as a new transaction: reconcile against the connector and the execution audit events for this businessTransactionId. authorizationId: 381ef27a-0955-4085-9e5d-e4223fef2986. | packages/runtime/src/errors/ExecutionRecordIncompleteError.ts |
EXTERNAL_CONNECTOR_CHANGE_NOT_FOUND | 404 | approveExternalConnectorChange, rejectExternalConnectorChange | External connector change ‘00000000-0000-0000-0000-000000000000’ not found. | packages/shared/src/errors/external-connector-change-not-found-error.ts |
EXTERNAL_ENDPOINT_ADDRESS_REFUSED | 400 | approveBusinessSignalSourceChange, approveExternalConnectorChange, proposeBusinessSignalSourceChange, proposeExternalConnectorChange | The endpoint host ‘erp-internal.example.com’ resolves to an address that is not public (10.0.0.7). | packages/api/src/routes/business-signal-sources.ts |
INTENT_REQUIRED | 400 | packages/shared/src/errors/intent-required-error.ts | ||
INVALID_AUTHORITY_GRANT | 400 | approveAuthorityGrantChange, proposeAuthorityGrantChange | capability must be namespace:verb, at most 128 characters, matching ^[a-z][a-z0-9](?:[-_][a-z0-9]+):[a-z][a-z0-9](?:[-_][a-z0-9]+)$. | packages/api/src/routes/authority-grants.ts |
INVALID_BUSINESS_SIGNAL_SOURCE | 400 | proposeBusinessSignalSourceChange | name must match ^[a-z0-9][a-z0-9-]$, the form a policy’s signalSources uses. | packages/api/src/routes/business-signal-sources.ts |
INVALID_EXTERNAL_CONNECTOR | 400 | proposeExternalConnectorChange | The namespace ‘paytm’ belongs to a built in connector. Use another namespace. | packages/api/src/routes/external-connectors.ts |
INVALID_SANDBOX_APPROVAL_REQUEST | 400 | createSandboxApproval | The sandbox approver signs only for capability “sandbox:receipt”. | packages/api/src/routes/sandbox-approvals.ts |
NO_APPROVED_POLICY_VERSION | 409 | getPolicyInEffect | Every request for “paytm:refund” is refused right now: no version of policy “customer-refund”, which capability “paytm:refund” requires, has been approved through policy governance. | packages/api/src/routes/policy-in-effect.ts |
NON_HUMAN_CALLER_DENIED | 403 | approveApprovalIssuerChange, approveAuthorityGrantChange, approveBusinessSignalSourceChange, approveExternalConnectorChange, approvePolicyChange, finalizeExecutionIntent, listApprovalIssuerChanges, listApprovalIssuers, listAuthorityGrantChanges, listAuthorityGrants, listBusinessSignalSourceChanges, listBusinessSignalSources, listExternalConnectorChanges, listExternalConnectors, listPendingPolicyChanges, listUnfinalizedExecutionIntents, proposeApprovalIssuerChange, proposeAuthorityGrantChange, proposeBusinessSignalSourceChange, proposeExternalConnectorChange, proposePolicyChange, rejectApprovalIssuerChange, rejectAuthorityGrantChange, rejectBusinessSignalSourceChange, rejectExternalConnectorChange, rejectPolicyChange, resolveExecutionIntent | This action requires a caller credential provisioned as a verified human (credentialHolderType: USER). | packages/shared/src/errors/non-human-caller-denied-error.ts |
NONCE_ALREADY_CONSUMED | 409 | packages/shared/src/errors/nonce-already-consumed-error.ts | ||
OVERRIDE_NOT_ALLOWED | 409 | packages/shared/src/errors/override-not-allowed-error.ts | ||
PENDING_POLICY_CHANGE_NOT_FOUND | 404 | approvePolicyChange, rejectPolicyChange | Pending Policy Change ‘00000000-0000-0000-0000-000000000000’ not found. | packages/shared/src/errors/pending-policy-change-not-found-error.ts |
POLICY_DENIED | 403 | createTransaction, executeTransaction | Execution rejected: Vendor payment rejected because the assessed payment risk exceeds the maximum permitted threshold. | |
POLICY_NOT_FOUND | 404 | packages/shared/src/errors/policy-not-found-error.ts | ||
POLICY_VERSION_UNAVAILABLE | 503 | getPolicyInEffect | Every request for “paytm:refund” is refused right now: the version of policy “customer-refund” in effect for capability “paytm:refund” could not be looked up: database unreachable. | packages/api/src/routes/policy-in-effect.ts |
RATE_LIMITED | 429 | packages/api/src/middleware/rate-limit.ts | ||
RECEIPT_GENERATION_FAILED | 409 | generateReceipt | Execution Trust Record must be successfully verified before a Receipt can be generated. | packages/runtime/src/errors/ReceiptGenerationError.ts |
SAME_ACTOR_CANNOT_APPROVE_OWN_CHANGE | 403 | approveApprovalIssuerChange, approveAuthorityGrantChange, approveBusinessSignalSourceChange, approveExternalConnectorChange, approvePolicyChange, rejectApprovalIssuerChange, rejectAuthorityGrantChange, rejectBusinessSignalSourceChange, rejectExternalConnectorChange, rejectPolicyChange | Pending Policy Change ‘307d8265-1171-49a4-b13f-fc3d3ae323e3’ was proposed by this same caller — the proposer (maker) may not also approve or reject it (checker). | packages/shared/src/errors/same-actor-cannot-approve-own-change-error.ts |
SIGNING_UNAVAILABLE | 503 | packages/runtime/src/errors/SigningUnavailableError.ts | ||
STEP_UP_AUTHORIZATION_INVALID | 403 | approveApprovalIssuerChange, approveAuthorityGrantChange, approveBusinessSignalSourceChange, approveExternalConnectorChange, approvePolicyChange, rejectApprovalIssuerChange, rejectAuthorityGrantChange, rejectBusinessSignalSourceChange, rejectExternalConnectorChange, rejectPolicyChange | The step-up authorization envelope is missing, invalid, expired, replayed, or does not match this request. | packages/shared/src/errors/step-up-authorization-invalid-error.ts |
TENANT_NOT_ALLOWED | 403 | packages/api/src/routes/execute.ts | ||
VERIFICATION_FAILED | 404 | generateReceipt, replayTransaction, verifyTransaction | Execution Trust Record not found. | packages/runtime/src/errors/VerificationFailedError.ts |