Skip to content
Gestalt

Reference: refusal codes

Status: shape-only inventory. The codes here are documented from the cloud handlers and SDK fixtures. The full taxonomy is not yet a stable enum; production will need a published taxonomy with stability guarantees. See 022 gap report item 18.

A refusal in Gestalt is not an error. It is a structured finding about why an act could not enter the cited reality. Every refusal carries a failed_gate, a refusal_reason (the code), and may carry remedy_hint, required_evidence, required_intervention, possible_projection_path, and whether_failure_is_recordable.

This page is the documented inventory of codes you may see today, grouped by family.

Auth and session

Section titled “Auth and session”
session_expired               bearer token has expired
session_tampered              bearer token signature does not verify
scope_mismatch                token's scopes do not include the operation
token_tampered                bearer token contents tampered
cross_tenant_access           call attempts cross-tenant access

Returned at the membrane authentication layer.

Intent and commit

Section titled “Intent and commit”
required_evidence_missing     a required evidence_bundle was not cited
authority_package_missing     no active authority package supports this capability
authority_package_stale       cited package is past its freshness window
standing_missing              the actor does not have standing for this act
standing_stale                actor's standing has lapsed
capability_unrecognized       cited capability is not known to the runtime
capability_superseded         cited capability has been superseded
effect_grammar_violation      proposed effects exceed the capability's declared grammar

Shop / hosted operator

Section titled “Shop / hosted operator”
shop_prepare_token_expired
shop_prepare_token_used
hosted_operator_grant_missing
hosted_operator_grant_revoked
hosted_operator_scope_mismatch

Authority packages

Section titled “Authority packages”
authority_package_tamper_refused
authority_package_stale
authority_package_self_activation_refused
authority_package_activation_requirements_missing
authority_package_revocation_unauthorized

Authority context / presence

Section titled “Authority context / presence”
m13_wrong_actor
m13_wrong_vessel
m13_human_presence_cannot_create_standing
m13_session_revoke_unauthorized
m13_key_rotate_unauthorized

Capability publication / policy

Section titled “Capability publication / policy”
capability_manifest_malformed
capability_manifest_imports_unresolved
capability_manifest_imports_cyclic
capability_publisher_unsigned        (production-only)
capability_attestation_missing       (production-only)
capability_self_publication_refused
capability_policy_evaluation_failed

Effects

Section titled “Effects”
effect_human_presence_required
effect_idempotency_key_collision
effect_capability_grammar_violation
effect_adapter_unknown

Economy

Section titled “Economy”
economic_invoice_evidence_missing
economic_payment_evidence_missing
economic_bookkeeping_evidence_incomplete
economic_closure_surface_open

Evidence / connectors

Section titled “Evidence / connectors”
connector_fixture_only                  request.fixture must be true today
evidence_stale                          stale: true was provided
connector_tenant_scope_mismatch         outside_tenant: true was provided
connector_idempotency_collision
connector_evidence_kind_unknown
human_presence_creates_standing_refused
identity_fallback_creates_standing_refused

Reality

Section titled “Reality”
reality_unspecified
reality_record_cites_projected
reality_projected_cites_other_projection
reality_promotion_authority_missing
reality_promotion_atom_missing
reality_discard_attempts_delete

Proof / receipt

Section titled “Proof / receipt”
missing_entitlement
proof_entitlement_missing
proof_disclosure_scope_unauthorized

Human auth

Section titled “Human auth”
human_auth_face_match_consent_missing
human_auth_passkey_user_not_verified
human_auth_passkey_binding_unknown
human_auth_challenge_expired
human_auth_challenge_replayed

Default posture (from contract)

Section titled “Default posture (from contract)”

The contract publishes a default posture map that tells you the default refusal mode for several conditions:

{
  "missing_standing": "refuse",
  "missing_authority_package": "pend",
  "stale_authority_package": "refuse",
  "low_confidence_extraction": "pend",
  "cross_tenant_access": "refuse",
  "projection_promotion_without_evidence": "refuse"
}

refuse produces an outcome: "refused" with the corresponding code. pend produces outcome: "pending" with a pending action.

See default-posture.md.

How to handle a refusal

Section titled “How to handle a refusal”
  1. Read the code. Map it to the canonical meaning above.
  2. Read the body. It usually includes requiredEvidence / requiredIntervention / remedyHint.
  3. Surface it. A Koerper should display the refusal as a structured “this could not be admitted because ; to fix, .” Not as a generic error.
  4. Respond. Gather the missing evidence, request the missing intervention, or open a projection if the body suggests possible_projection_path.

What refusal codes are not

Section titled “What refusal codes are not”
  • Not HTTP error codes. A refused operation returns HTTP 2xx.
  • Not bugs. They are governed facts.
  • Not strings to display directly. They are stable identifiers for code paths; human prose belongs in the Koerper.
  • Not exhaustive (yet). New codes will appear as the runtime fills gaps. Always introspect via /v1/refusals/codes for the current set.
Section titled “Where to read next”