# Error details and recovery matrix

> Recovery conventions. The examples illustrate the protocol and don't represent real resources.


## Deterministic state machine

Recovering a committed result for the same key takes precedence over the current ETag and catalog checks. If authentication, header, catalog revision, or If-Match checks fail before the write intent is accepted, no receipt is created. A query can return 404 RPA_REQUEST_NOT_COMMITTED + safeToRetrySameKey=true only when there is no original receipt, the instance has fully recovered, and the identity matches the original account/team. Don't treat any other 404 as this guarantee.

After acceptance, a deterministic structural or semantic failure, or a failed pre-transaction business check, can be recorded as failed. originalStatus/safeError identify the original error, and result=null. This proves that the intent made no business commit and that the key is finalized. Resending only replays the failure. Modify the request, validate again, and then create a new intent. When the transaction outcome can't be proven, the state must be unknown and can't be disguised as failed. After a business commit, the state can't change to failed. It is committed while publication is incomplete, and completed after publication is recovered.

| Observation | Meaning for this attempt / valid receipt | Next step |
|  --- | --- | --- |
| 412 RPA_VERSION_CONFLICT / 428 RPA_PRECONDITION_REQUIRED | This attempt was rejected before acceptance, so it doesn't create a failed receipt. You still need to check the actual state of any concurrent or earlier request with the same key. | Query the original key. Only when it is clearly not committed, GET, merge, and validate again. If the body or If-Match changes, use a new key. If the query shows a committed state, follow that state. Don't assume that the 412 overrides the earlier result. |
| 409 RPA_CATALOG_CHANGED | Rejected before acceptance; same as above. | Query the original key. After it is clearly not committed, refresh the catalog. You can recover with the original key only if just the catalog header changes and method/path/body/If-Match stay the same. |
| Write 422 / registered business failure | There is no receipt if the write wasn't accepted. If it was accepted, the receipt can be failed. Neither case includes a partial template write. | Check the state. After failed or an explicit NOT_COMMITTED, fix the request, validate again, and send the new intent with a new key. |
| Disconnect / 504 / uncertain 5xx | The commit outcome can't be determined from HTTP. | Query with the original key. Never switch to a new key and redo the write directly. |
| accepted | Still in flight; the commit isn't confirmed. | Use bounded polling. Don't register the intent again concurrently. |
| committed | Committed and waiting for publication. | Keep observing or recovering. Don't repeat the write. |
| completed | The registered operation is complete. This isn't a browser terminal state. | Use originalStatus/result. Before making changes, GET the latest body and ETag. Don't use the version from an old result as the current lock. |
| failed | A final failure, confirmed to have no business commit; result=null. | Read safeError. Fix or remove the cause of the failure, validate again, and then use a new key. Don't loop on the original key. |
| unknown | The outcome of the business transaction can't be confirmed. | Stop automatic writes. Verify the resource and the request tracing information. |
| 404 RPA_REQUEST_NOT_COMMITTED + safeToRetrySameKey=true | Confirmed that nothing was committed in the original account/team. | If the original intent is unchanged, recover with the original key. If you need to change the body or If-Match, use a new key. |
| Ordinary 404, 403, or 503 during recovery | This doesn't prove that there was no business effect. | Restore the identity, permissions, or host. Wait or verify, and don't redo the write. |
| 410 RPA_REQUEST_EXPIRED | The replay window has passed. | Check the tombstone's resourceId/originalStatus and the readable resource. Then decide whether a new intent is really needed. |
| 409 RPA_TEMPLATE_VERSION_CONFLICT from POST validations | The saved-source.version or inline base.version is stale. This validation has no write receipt. | GET the current template, keep concurrent changes, merge the candidate, and then validate again with the new base.version. |
| 200 with valid=false from POST validations | Validation finished, and the candidate didn't pass. | Use issue.path to locate and fix each problem, then validate again. Don't save. If the next response is unknown, treat the result as unknown. |
| 503 RPA_VALIDATION_TIMEOUT from POST validations | The read-only budget is exhausted. | Validate again after the Retry-After delay. Don't query a write receipt. |


Even without a new write of your own, other callers can change the version. The reported currentVersion is only a snapshot from the time of the check. Only a GET of the current template gives you a new base for writes. runtimeChecks=[] only means that no pending checks are listed. It doesn't prove the page state, real execution success, or anything about check reasons that the server didn't list.

## Schema for details

In the [HTTP Schema](/browser-rpa/local-api#local-machine-readable-contract), Error.allOf constrains details by code: a known code never falls back to an arbitrary object. VersionConflictDetails must include all of templateId/expectedVersion/currentVersion. A 412 can have details=null to avoid leaking additional resource information. For a 409 stale template version, details must be provided when the caller has access to the template. For NOT_COMMITTED, details can't be null, and safeToRetrySameKey can only be true. Other errors without a dedicated type still allow a secret-free extension object or null.

issue.path is always relative to the current request. For node-edits, if an issue points to a newly submitted node, the path is `/operations/<i>/node/...`. If a remove, move, or similar operation causes an error in an existing node, the path is the `/operations/<i>` that caused the problem. When details.workflowPath is present, it gives the first issue's location in the final complete TemplateWrite and starts with /workflow. Locate later issues with nodeId/field in the final candidate. Don't apply the single workflowPath to all issues. For inline validation, issue.path already starts at /source/template/workflow, and ValidationReport has no error.details. When there is no specific workflow location, workflowPath can be omitted or details can be null.

## Complete error examples

### 404: explicitly not committed

```json
{
  "error": {
    "code": "RPA_REQUEST_NOT_COMMITTED",
    "message": "Simulated error; decide based on the code",
    "retryable": true,
    "issues": [],
    "details": {
      "safeToRetrySameKey": true
    }
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### 409: stale inline base or saved-source version

```json
{
  "error": {
    "code": "RPA_TEMPLATE_VERSION_CONFLICT",
    "message": "Simulated error; decide based on the code",
    "retryable": false,
    "issues": [],
    "details": {
      "templateId": "template_example",
      "expectedVersion": 1,
      "currentVersion": 2
    }
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### 412: stale If-Match

```json
{
  "error": {
    "code": "RPA_VERSION_CONFLICT",
    "message": "Simulated error; decide based on the code",
    "retryable": false,
    "issues": [],
    "details": {
      "templateId": "template_example",
      "expectedVersion": 1,
      "currentVersion": 2
    }
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### 422: node edits cause a reference error in the final workflow

```json
{
  "error": {
    "code": "RPA_VALIDATION_FAILED",
    "message": "Simulated error; decide based on the code",
    "retryable": false,
    "issues": [
      {
        "code": "RPA_REFERENCE_NOT_FOUND",
        "message": "The node referenced by the end node doesn't exist",
        "severity": "error",
        "path": "/operations/0",
        "nodeId": "end",
        "field": "message",
        "expected": "An earlier output that exists in the current scope",
        "suggestion": "Fix the end node reference in the same batch of operations"
      }
    ],
    "details": {
      "workflowPath": "/workflow/nodes/3/data/inputsValues/message"
    }
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### 409: stale catalog

```json
{
  "error": {
    "code": "RPA_CATALOG_CHANGED",
    "message": "Simulated error; decide based on the code",
    "retryable": true,
    "issues": [],
    "details": {
      "expectedCatalogRevision": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "currentCatalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### 410: replay expired

```json
{
  "error": {
    "code": "RPA_REQUEST_EXPIRED",
    "message": "Simulated error; decide based on the code",
    "retryable": false,
    "issues": [],
    "details": {
      "resourceId": "template_example",
      "originalStatus": 201
    }
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

Without access to the template, the server returns 403/404 first, not a version conflict code. So whenever 409 RPA_TEMPLATE_VERSION_CONFLICT is returned, VersionConflictDetails is always present. There is no "details can be omitted when access is denied" branch for this code.

### Registered failure receipt (200)

```json
{
  "data": {
    "key": "8aefcc5a-dce8-4e5b-a494-26f404475850",
    "operation": "editTemplateNodes",
    "state": "failed",
    "createdAt": 1793318400000,
    "updatedAt": 1793318400001,
    "replayAvailable": true,
    "resourceId": "template_example",
    "originalStatus": 422,
    "result": null,
    "safeError": {
      "code": "RPA_VALIDATION_FAILED",
      "message": "The reference doesn't exist"
    }
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

In the current implementation, input and semantic validation failures all happen before the commit. So there is usually no failed receipt, and the query returns an explicit NOT_COMMITTED. That response has retryable=true and safeToRetrySameKey=true. This doesn't mean you can change the body under the same key. A corrected intent still needs a new key.