Errors
state_proof_integrity_fail
409 — the stored filing proof bytes no longer hash to the recorded content_hash, so the captured evidence is not tamper-evident.
Last updated
Cause
When the browser agent prepares a filing, it captures proof at the last reviewable screen before submit — the canonicalized field dump, the form field values, and the source-byte hashes of any uploaded identity images — and records a content_hash over exactly those deterministic inputs. The proof bytes live in a write-once, object-locked bucket; the content_hash folds into the immutable audit chain and its daily Merkle anchor.
GET /entities/{id}/filing_proof re-verifies that bond on every read: it recomputes SHA-256 over the stored bytes and compares the result to the recorded content_hash. proof_integrity_fail fires when those two values disagree. That disagreement means the stored evidence is no longer the evidence that was anchored — a byte was altered, a payload was blanked while the hash was left intact, or the object was replaced. The read refuses to hand back proof it cannot stand behind, rather than returning bytes that silently fail their own integrity check.
This is a fail-closed guard, not a transient fault. Retrying the same request returns the same 409 until the underlying object is restored, because the mismatch is a property of the stored bytes, not of the request.
Fix
- Do not treat the returned proof as authoritative. A
proof_integrity_failmeans the captured evidence for this filing cannot be verified and must not be relied on for a submission decision. - Re-read the audit chain for the run. The chained
AuditEntryrows and the Merkle anchor record the originalcontent_hash; compare it against what the bucket now holds to confirm the divergence. - Escalate to a human and to platform support with the entity id and the run's
content_hash. A proof byte changing after capture is a tamper or storage-integrity event, not an application bug a caller can retry away. - Re-prepare the filing once the integrity event is understood. A fresh run captures fresh proof and a fresh anchor; the prior, unverifiable bundle stays on record as the evidence of the incident.
Related codes
state_optimistic_lock_conflict— the resource was modified concurrently and the write cannot apply against a stale version.not_found_resource— the entity has no captured proof, or the token has no read grant on it.