Errors
state_transition_invalid
409 — the requested transition is not permitted from the resource's current state.
Last updated
Cause
Every long-lived Matter resource — Entity, Filing, Round, Dissolution, Document, SigningEnvelope — has an explicit state machine. state_transition_invalid fires when a mutating call tries to drive the resource through a transition that the machine does not declare from the current state.
The most common example is calling dissolve on an entity that is already in dissolved state, or calling submit on a Round that is in closed. The response includes current_state, attempted_transition, and allowed_transitions[] extension fields so the caller — including an LLM agent — can re-plan without round-tripping for state.
Matter state machines are intentional, not incidental. A transition is excluded because the legal or business consequences would be incoherent, not because no one got around to implementing it. The fix is always to act through the legal predecessor, never to bypass the check.
Fix
- Read the
allowed_transitions[]field on the problem response. It lists the verbs the resource will accept from its current state. - If your goal is achievable through a legal predecessor (for example, withdraw before re-submitting), call that transition first.
- If your goal is genuinely incompatible with the current state (dissolving an already-dissolved entity), the operation is complete — surface the existing state to the user and stop.
- Never poll the same transition expecting it to succeed eventually. State machines are deterministic; if the transition is invalid now, it will remain invalid until the resource is moved to a state that allows it.
Related codes
state_authorisation_required— the transition is in principle allowed but lacks an authorising Resolution.state_cap_table_invariant_violated— the transition would break an invariant.state_optimistic_lock_conflict— the state changed concurrently.