First Write

Use a mutation whose generated operation declares the optional dryRun query parameter, such as POST /transactions. Send the exact payload with dryRun=true first:

curl 'https://api.vrplatform.app/transactions?dryRun=true' \
  -X POST \
  -H 'content-type: application/json' \
  -H 'x-api-key: <team-api-key>' \
  -H 'x-team-id: <team-id>' \
  --data @transaction.json

A minimal transaction.json for an expense (amounts are in cents):

{
  "type": "expense",
  "date": "2026-07-01",
  "description": "Pool cleaning June",
  "contactId": "33333333-3333-4333-8333-333333333333",
  "lines": [
    {
      "description": "Pool cleaning",
      "amount": 12500,
      "listingId": "11111111-1111-4111-8111-111111111111"
    }
  ]
}

A successful dry run returns the normal success shape, then rolls the database transaction back. IDs and unique references in that response are provisional. Discard them. Abbreviated:

{
  "id": "44444444-4444-4444-8444-444444444444",
  "type": "expense",
  "date": "2026-07-01",
  "status": "active",
  "lines": [{ "id": "...", "amount": 12500, "party": "owners", "lock": {} }]
}

A failed dry run returns the same structured error body as a real write (see the Error contract):

{
  "code": "BAD_REQUEST",
  "message": "Human-readable summary",
  "issues": [],
  "context": {}
}

Apply The Write

1. Load referenced options and current response-owned state.
2. Apply deterministic rules for immediate feedback.
3. Request a dedicated preview when calculated consequences are needed.
4. Dry-run the complete proposed payload when the operation supports it.
5. Render structured code, issues, and context on failure.
6. Confirm with the user.
7. Send the same request without dryRun.
8. Handle a final-write conflict and re-read the resource.

Preflight does not reserve state; the server still has the final say at the real write. Continue with the shared Requests, Locks & Issues and the full Dry Run Mode guarantee.