# Chi tiết lỗi và ma trận khôi phục

> Quy ước khôi phục. Các ví dụ minh họa giao thức và không đại diện cho tài nguyên thật.


## Máy trạng thái xác định

Việc khôi phục kết quả đã commit của cùng một khóa được ưu tiên hơn các bước kiểm tra ETag và danh mục hiện tại. Nếu bước kiểm tra xác thực truy cập, header, bản sửa đổi danh mục hoặc If-Match thất bại trước khi ý định ghi được chấp nhận, sẽ không có biên nhận nào được tạo. Truy vấn chỉ có thể trả về 404 RPA_REQUEST_NOT_COMMITTED + safeToRetrySameKey=true khi không có biên nhận ban đầu, instance đã khôi phục hoàn toàn và danh tính khớp với tài khoản/nhóm ban đầu. Không coi bất kỳ phản hồi 404 nào khác là sự bảo đảm này.

Sau khi được chấp nhận, một lỗi cấu trúc hoặc lỗi ngữ nghĩa có tính xác định, hoặc một bước kiểm tra nghiệp vụ trước giao dịch bị thất bại, có thể được ghi nhận là failed. originalStatus/safeError xác định lỗi ban đầu, và result=null. Điều này chứng minh rằng ý định không tạo commit nghiệp vụ nào và khóa đã được chốt. Gửi lại chỉ phát lại lỗi đó. Hãy sửa yêu cầu, xác thực lại, rồi tạo một ý định mới. Khi không thể chứng minh kết quả giao dịch, trạng thái phải là unknown và không được ngụy trang thành failed. Sau khi đã commit nghiệp vụ, trạng thái không thể chuyển thành failed. Trạng thái là committed khi việc công bố chưa hoàn tất, và là completed sau khi việc công bố được khôi phục.

| Kết quả quan sát được | Ý nghĩa đối với lần thử này / biên nhận hợp lệ | Bước tiếp theo |
|  --- | --- | --- |
| 412 RPA_VERSION_CONFLICT / 428 RPA_PRECONDITION_REQUIRED | Lần thử này bị từ chối trước khi được chấp nhận, nên không tạo biên nhận failed. Bạn vẫn cần kiểm tra trạng thái thực tế của mọi yêu cầu đồng thời hoặc trước đó dùng cùng khóa. | Truy vấn khóa ban đầu. Chỉ khi chắc chắn rằng yêu cầu chưa được commit, hãy GET, hợp nhất và xác thực lại. Nếu phần thân hoặc If-Match thay đổi, hãy dùng khóa mới. Nếu truy vấn cho thấy trạng thái đã commit, hãy làm theo trạng thái đó. Không giả định rằng phản hồi 412 ghi đè kết quả trước đó. |
| 409 RPA_CATALOG_CHANGED | Bị từ chối trước khi được chấp nhận; giống như trên. | Truy vấn khóa ban đầu. Sau khi chắc chắn rằng yêu cầu chưa được commit, hãy làm mới danh mục. Bạn chỉ có thể khôi phục bằng khóa ban đầu nếu chỉ header danh mục thay đổi, còn phương thức/đường dẫn/phần thân/If-Match giữ nguyên. |
| 422 khi ghi / lỗi nghiệp vụ đã được đăng ký | Không có biên nhận nếu thao tác ghi chưa được chấp nhận. Nếu đã được chấp nhận, biên nhận có thể là failed. Không trường hợp nào có việc ghi mẫu một phần. | Kiểm tra trạng thái. Sau failed hoặc NOT_COMMITTED tường minh, hãy sửa yêu cầu, xác thực lại và gửi ý định mới bằng khóa mới. |
| Mất kết nối / 504 / 5xx không chắc chắn | Không thể xác định kết quả commit từ HTTP. | Truy vấn bằng khóa ban đầu. Tuyệt đối không chuyển sang khóa mới để ghi lại trực tiếp. |
| accepted | Vẫn đang được xử lý; commit chưa được xác nhận. | Thăm dò có giới hạn. Không đăng ký lại ý định này song song. |
| committed | Đã commit và đang chờ công bố. | Tiếp tục quan sát hoặc khôi phục. Không lặp lại thao tác ghi. |
| completed | Thao tác đã đăng ký đã hoàn tất. Đây không phải là trạng thái kết thúc của trình duyệt. | Dùng originalStatus/result. Trước khi thay đổi, hãy GET phần thân và ETag mới nhất. Không dùng phiên bản trong kết quả cũ làm khóa phiên bản hiện tại. |
| failed | Lỗi cuối cùng, đã xác nhận không có commit nghiệp vụ nào; result=null. | Đọc safeError. Sửa hoặc loại bỏ nguyên nhân gây lỗi, xác thực lại, rồi dùng khóa mới. Không lặp lại với khóa ban đầu. |
| unknown | Không thể xác nhận kết quả của giao dịch nghiệp vụ. | Dừng các thao tác ghi tự động. Kiểm tra tài nguyên và thông tin truy vết yêu cầu. |
| 404 RPA_REQUEST_NOT_COMMITTED + safeToRetrySameKey=true | Đã xác nhận rằng chưa có gì được commit trong tài khoản/nhóm ban đầu. | Nếu ý định ban đầu không thay đổi, hãy khôi phục bằng khóa ban đầu. Nếu cần thay đổi phần thân hoặc If-Match, hãy dùng khóa mới. |
| 404, 403 hoặc 503 thông thường trong khi khôi phục | Điều này không chứng minh rằng không có tác động nghiệp vụ nào. | Khôi phục danh tính, quyền hoặc ứng dụng chủ (host). Hãy chờ hoặc kiểm tra, và không ghi lại. |
| 410 RPA_REQUEST_EXPIRED | Đã quá thời hạn phát lại. | Kiểm tra resourceId/originalStatus của bản ghi tombstone và tài nguyên còn đọc được. Sau đó quyết định xem có thực sự cần ý định mới hay không. |
| 409 RPA_TEMPLATE_VERSION_CONFLICT từ POST validations | saved-source.version hoặc base.version của nguồn inline đã cũ. Lần xác thực này không có biên nhận ghi. | GET mẫu hiện tại, giữ lại các thay đổi đồng thời, hợp nhất bản đề xuất, rồi xác thực lại với base.version mới. |
| 200 kèm valid=false từ POST validations | Bước xác thực đã hoàn tất, và bản đề xuất không vượt qua. | Dùng issue.path để xác định vị trí và sửa từng vấn đề, rồi xác thực lại. Không lưu. Nếu không biết được phản hồi tiếp theo, hãy coi kết quả là chưa xác định. |
| 503 RPA_VALIDATION_TIMEOUT từ POST validations | Đã dùng hết ngân sách thời gian của bước xác thực chỉ đọc. | Xác thực lại sau khoảng thời gian chờ Retry-After. Không truy vấn biên nhận ghi. |


Ngay cả khi bạn không ghi gì mới, các bên gọi khác vẫn có thể thay đổi phiên bản. currentVersion được báo cáo chỉ là bản chụp nhanh tại thời điểm kiểm tra. Chỉ có GET mẫu hiện tại mới cho bạn base mới để ghi. runtimeChecks=[] chỉ có nghĩa là không có bước kiểm tra đang chờ nào được liệt kê. Điều này không chứng minh trạng thái của trang, việc thực thi thực tế thành công, hay bất cứ điều gì về các lý do kiểm tra mà máy chủ không liệt kê.

## Schema của details

Trong [Schema HTTP](/vi/browser-rpa/local-api#h%E1%BB%A3p-%C4%91%E1%BB%93ng-c%E1%BB%A5c-b%E1%BB%99-d%E1%BA%A1ng-m%C3%A1y-%C4%91%E1%BB%8Dc-%C4%91%C6%B0%E1%BB%A3c), Error.allOf ràng buộc details theo code: một mã đã biết không bao giờ rơi về một đối tượng tùy ý. VersionConflictDetails phải có đủ templateId/expectedVersion/currentVersion. Phản hồi 412 có thể có details=null để tránh làm lộ thêm thông tin về tài nguyên. Với lỗi 409 do phiên bản mẫu đã cũ, details phải được cung cấp khi bên gọi có quyền truy cập mẫu. Với NOT_COMMITTED, details không thể là null, và safeToRetrySameKey chỉ có thể là true. Các lỗi khác không có kiểu chuyên biệt vẫn cho phép một đối tượng mở rộng không chứa bí mật hoặc null.

issue.path luôn tương đối so với yêu cầu hiện tại. Với node-edits, nếu một vấn đề trỏ đến một nút mới được gửi, đường dẫn là `/operations/<i>/node/...`. Nếu một thao tác remove, move hoặc tương tự gây lỗi ở một nút hiện có, đường dẫn là `/operations/<i>` của thao tác đã gây ra vấn đề. Khi có details.workflowPath, trường này cho biết vị trí của vấn đề đầu tiên trong TemplateWrite hoàn chỉnh cuối cùng và bắt đầu bằng /workflow. Xác định vị trí các vấn đề sau đó bằng nodeId/field trong bản đề xuất cuối cùng. Không áp dụng một workflowPath duy nhất cho mọi vấn đề. Với xác thực inline, issue.path đã bắt đầu từ /source/template/workflow, và ValidationReport không có error.details. Khi không có vị trí cụ thể trong quy trình, workflowPath có thể bị bỏ qua hoặc details có thể là null.

## Ví dụ lỗi đầy đủ

### 404: xác nhận rõ ràng là chưa commit

```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: base của nguồn inline hoặc phiên bản saved-source đã cũ

```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: If-Match đã cũ

```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: chỉnh sửa nút gây lỗi tham chiếu trong quy trình cuối cùng

```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: danh mục đã cũ

```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: hết hạn phát lại

```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"
  }
}
```

Khi không có quyền truy cập mẫu, máy chủ trả về 403/404 trước, không trả về mã xung đột phiên bản. Vì vậy, mỗi khi 409 RPA_TEMPLATE_VERSION_CONFLICT được trả về, VersionConflictDetails luôn có mặt. Mã này không có nhánh "có thể bỏ qua details khi bị từ chối truy cập".

### Biên nhận lỗi đã đăng ký (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"
  }
}
```

Trong cách triển khai hiện tại, mọi lỗi xác thực đầu vào và xác thực ngữ nghĩa đều xảy ra trước khi commit. Vì vậy thường không có biên nhận failed, và truy vấn trả về NOT_COMMITTED tường minh. Phản hồi đó có retryable=true và safeToRetrySameKey=true. Điều này không có nghĩa là bạn có thể thay đổi phần thân với cùng khóa. Ý định đã sửa vẫn cần khóa mới.