Errors and operations

Reason codes

RW_REQUEST_001 extends the original specification table: request schema failures need a code distinct from policy failures.

A denial is not a revert

When the gateway denies an operation before broadcast, it returns a structured JSON-RPC error. No transaction exists, so there is no transaction hash and no revert. An EVM revert happens only when an executed transaction reverts on chain.

{
  "error": {
    "code": -32090,
    "message": "Ravelin Wall denied the operation",
    "data": {
      "reason_code": "RW_BUDGET_001",
      "request_id": "rw_req_example",
      "retryable": true,
      "transaction_hash": null
    }
  }
}

Retry semantics

• Retry only operations created with an idempotency key. A retry with the same key returns the original result.
• Use bounded exponential backoff. Never retry a financial action without proof that it cannot execute twice.
• RW_LOOP_001 is not retryable: change the intent, or wait out the cooldown with a new request.

Operation states

Approval, signing, submission, inclusion and success are separate states, never conflated.

Failure behaviour

Recovery procedures

1. Denied (terminal). Read reason_code and message. Change the intent or the policy; never retry the same request. Nothing was signed, so there is nothing to reconcile.
2. Retryable denial. If retryable is true (budget, rate, fee, state, chain), wait for the condition to clear and resubmit with the same idempotency key. A repeat with the same key returns the original result.
3. Pending approval. Poll the approval or subscribe to its status. If it expires or the policy version changes, the pending authorization is invalidated and its reservation released; submit a new request.
4. Submitted, outcome unknown. Do not resubmit. Query the operation until it reaches a final state; the reservation is held until the receipt is reconciled, so a retry cannot create a second execution.
5. Emergency stop. New operations are denied with RW_PAUSED_001. Resume only after the stop is released by an authorized operator and health checks pass.

RPC and bundler outages

When the RPC endpoint, fee estimator or bundler is unavailable, new authorizations fail closed (RW_FEE_001, RW_CHAIN_001). Already-submitted operations keep their state and reservation until a receipt is verified; an unverified or disputed receipt never finalizes spend. Retries use bounded exponential backoff and the original idempotency key.

Debugging

• Every response carries a request_id. Use it to find the audit record, which lists every check in evaluation order with its result and detail.
• Reproduce a decision locally: the reference evaluator is deterministic, so the same policy, request and state give the same result. The workbench and the console simulation run it in the browser.
• Check the policy version in the response against the version you expect to be active. Approvals and authorizations are bound to the version they were evaluated under.
• transaction_hash is null whenever nothing was broadcast. A non-null hash with a failed status is an EVM revert, which is different from a denial.