Documentation · Functionality

Guided failure modes

Production integrations fail in predictable ways. Use this cookbook before opening a support ticket. Quickstart.

Invalid proof

Symptom: Verify returns valid:false or HTTP 422 with policy errors.
Likely cause: Proof payload fails deterministic policy (e.g. minimum_rows_v1) or hash mismatch.
Fix: Re-read policy registry; resubmit proof with Idempotency-Key; check evidence digest.

Expired / closed relay room

Symptom: Publish/subscribe fails; client receives room_closed or quota_exceeded.
Likely cause: Idle timeout, hard session cap, or process restart (in-memory rooms).
Fix: Reconnect with backoff; recreate room; upgrade tier if hitting concurrent limits.

Mismatched settlement / contract IDs

Symptom: Verifier 404 or pipeline stages empty for contractId.
Likely cause: Wrong environment, typo, or ID from a different tenant.
Fix: Confirm PORTAL_URL / tenant; use pipelineRootHash if contractId is internal-only.

Duplicate claims

Symptom: HTTP 409 or idempotent replay of prior response.
Likely cause: Same Idempotency-Key reused with different body, or intentional retry.
Fix: Reuse key only for identical bodies; mint new key for new work items.

Partial release instruction

Symptom: Obligation state PARTIAL / RELEASING; webhook settlement.released with partial amount.
Likely cause: Milestone policy or HITL approved a subset of the obligation.
Fix: Licensee executes partial transfer on their rails; Flomisma only records the instruction.

HITL hold

Symptom: Auto-execute blocked; hitl.exception or pending human review.
Likely cause: Confidence below calibrated threshold or policy requires review.
Fix: Operator confirms/overrules via admin; do not treat as Flomisma fund release.

Failure modes · Flomisma