Responses and errors.

One envelope shape, success or failure. Branch on the group, not the code.

The envelope

Every result comes back the same shape, success or failure, with backend (mock or seam) and network on both, so a transcript alone says whether a call touched a real chain and which one.

{"ok": true, "backend": "seam", "network": "sepolia", "result": {...}}

error

{"ok": false, "backend": "seam", "network": "sepolia", "error": {"code": "...", "message": "...", "retryable": false}}

Branch on the group below, not the individual code. retryable on the error is the thing to trust — not a guess from the name.

The offer is wrong

OFFER_EXPIREDOFFER_UNKNOWNALREADY_SETTLEDNOT_YOUR_OFFERAMOUNT_MISMATCHINSUFFICIENT_NOTESINDEX_CONFLICTBuild a different offer. Retrying verbatim will not help.

Funding or identity policy

INSUFFICIENT_ALLOWANCEINSUFFICIENT_BALANCEChange the allowance or fund the account before a new attempt.

Durable operation state

OPERATION_CONFLICTRECONCILIATION_REQUIREDKeep the original operation_id. Inspect reconcile and follow its operator action.

Transient

SCREENING_UNAVAILABLEPROVER_UNAVAILABLEPROOF_EXPIREDSUBMIT_FAILEDRetry with backoff. PROOF_EXPIRED needs a fresh proof, not a resend.

Terminal

SCREENING_REJECTEDStop. Not transient.

Opaque

PROOF_FAILEDThe prover refused and gave no reason. Report it as unexplained.

Before any protocol code ran

INVALID_REQUESTIDENTITY_UNAVAILABLEFix the request or the key path. Never a chain-state problem.

A write takes one to four minutes. Do not create a new operation_id for one that appears stuck — call reconcile, then resume_operation with the original ID once its result permits it.