Responses and errors.

Each tool returns a result or an error. The error includes a code, a message, and a retry flag.

This page describes the Starknet backend. For Monad, see the Monad deal flow.

The envelope

All responses use the same envelope format, whether a call succeeds or fails. Every response includes backend (mock or seam) and network metadata, so logs identify the selected backend and network. These fields alone do not prove that a transaction reached the chain.

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

error

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

Use the groups below to find the relevant recovery steps. Check the retryable boolean field on the error object to determine if a call can be retried. Do not guess retry behavior from the error code name.

The offer is wrong

OFFER_EXPIREDOFFER_UNKNOWNALREADY_SETTLEDNOT_YOUR_OFFERAMOUNT_MISMATCHINSUFFICIENT_NOTESINDEX_CONFLICTRead the error message before another write. An expired offer needs new terms; insufficient notes need funding. If the deal is already settled, inspect its record instead of paying again.

Funding or identity policy

INSUFFICIENT_ALLOWANCEINSUFFICIENT_BALANCEAdjust the allowance or fund the account before retrying.

Durable operation state

OPERATION_CONFLICTRECONCILIATION_REQUIREDRetain the original operation_id, call reconcile, and follow the returned guidance.

Transient

SCREENING_UNAVAILABLEPROVER_UNAVAILABLEPROOF_EXPIREDSUBMIT_FAILEDFor reads, use the retryable flag and exponential backoff. For writes, call reconcile first and keep the original operation_id. If the journal permits recovery, resume_operation can submit again or rebuild an expired proof.

Terminal

SCREENING_REJECTEDDo not retry. This error is not transient.

Opaque

PROOF_FAILEDThe prover rejected the request without providing a reason. Report this as an unexplained failure.

Before any protocol code ran

INVALID_REQUESTIDENTITY_UNAVAILABLECorrect the request payload or key file path. This error never indicates a chain-state problem.

Proof generation can keep a write pending for minutes. A slow response does not prove that the call failed. Never create a new operation_id for a slow write, as this risks duplicate transactions and double payment. Call reconcile first to inspect state, then run resume_operation with the original operation_id when permitted.