Package google.rpc

Chỉ mục

Mã lỗi chính tắc cho API gRPC.

Đôi khi, có thể có nhiều mã lỗi. Dịch vụ phải trả về mã lỗi cụ thể nhất được áp dụng. Ví dụ: ưu tiên OUT_OF_RANGE hơn FAILED_PRECONDITION nếu áp dụng cả hai mã. Tương tự, hãy ưu tiên NOT_FOUND hoặc ALREADY_EXISTS hơn FAILED_PRECONDITION.

Enum
OK

Không phải là lỗi; được trả lại khi thành công.

Ánh xạ HTTP: 200 OK

CANCELLED

Thao tác đã bị huỷ, thường là do phương thức gọi.

Ánh xạ HTTP: Yêu cầu đã đóng ứng dụng 499

UNKNOWN

Lỗi không xác định. Ví dụ: lỗi này có thể được trả về khi giá trị Status nhận được từ một không gian địa chỉ khác thuộc về một không gian lỗi chưa được xác định trong không gian địa chỉ này. Ngoài ra, lỗi do những API không trả về đủ thông tin lỗi có thể được chuyển đổi thành lỗi này.

Ánh xạ HTTP: Lỗi máy chủ nội bộ 500

INVALID_ARGUMENT

Khách hàng đã chỉ định một đối số không hợp lệ. Xin lưu ý rằng thuộc tính này khác với FAILED_PRECONDITION. INVALID_ARGUMENT cho biết các đối số có vấn đề bất kể trạng thái của hệ thống (ví dụ: tên tệp không đúng định dạng).

Ánh xạ HTTP: Yêu cầu không hợp lệ 400

DEADLINE_EXCEEDED

Đã hết thời hạn trước khi thao tác có thể hoàn tất. Đối với những hoạt động thay đổi trạng thái của hệ thống, lỗi này có thể được trả về ngay cả khi thao tác đã hoàn tất thành công. Ví dụ: một phản hồi thành công từ máy chủ có thể bị trì hoãn đủ lâu đến thời hạn.

Ánh xạ HTTP: Hết thời gian chờ của cổng vào 504

NOT_FOUND

Không tìm thấy một số đối tượng được yêu cầu (ví dụ: tệp hoặc thư mục).

Lưu ý cho các nhà phát triển máy chủ: nếu yêu cầu bị từ chối đối với toàn bộ một nhóm người dùng, chẳng hạn như triển khai tính năng dần dần hoặc danh sách cho phép không được ghi nhận, thì NOT_FOUND có thể được sử dụng. Nếu yêu cầu bị từ chối đối với một số người dùng trong một lớp người dùng, chẳng hạn như kiểm soát quyền truy cập dựa trên người dùng, thì bạn phải sử dụng PERMISSION_DENIED.

Ánh xạ HTTP: Không tìm thấy 404

ALREADY_EXISTS

Mục mà ứng dụng khách cố gắng tạo (ví dụ: tệp hoặc thư mục) đã tồn tại.

Ánh xạ HTTP: Xung đột 409

PERMISSION_DENIED

Phương thức gọi không có quyền thực thi thao tác đã chỉ định. Không được sử dụng PERMISSION_DENIED cho các trường hợp bị từ chối do làm cạn kiệt tài nguyên (hãy dùng RESOURCE_EXHAUSTED thay cho các lỗi đó). Không được sử dụng PERMISSION_DENIED nếu không thể xác định phương thức gọi (hãy dùng UNAUTHENTICATED cho những lỗi đó). Mã lỗi này không ngụ ý rằng yêu cầu đó hợp lệ, hoặc pháp nhân được yêu cầu tồn tại hay đáp ứng các điều kiện tiên quyết khác.

Ánh xạ HTTP: 403 bị cấm

UNAUTHENTICATED

Yêu cầu không có thông tin xác thực hợp lệ cho thao tác này.

Ánh xạ HTTP: 401 Không được phép

RESOURCE_EXHAUSTED

Một số tài nguyên đã hết, có thể là hạn mức cho mỗi người dùng, hoặc có thể toàn bộ hệ thống tệp hết dung lượng.

Ánh xạ HTTP: 429 Quá nhiều yêu cầu

FAILED_PRECONDITION

Thao tác đã bị từ chối vì hệ thống không ở trạng thái cần thiết để thực thi thao tác. Ví dụ: thư mục cần xoá không phải thư mục trống, thao tác rmdir được áp dụng cho một thư mục không phải thư mục, v.v.

Trình triển khai dịch vụ có thể dựa vào những nguyên tắc sau để quyết định giữa FAILED_PRECONDITION, ABORTEDUNAVAILABLE: (a) Sử dụng UNAVAILABLE nếu ứng dụng chỉ có thể thử lại lệnh gọi không thành công. (b) Sử dụng ABORTED nếu khách hàng thử lại ở cấp cao hơn. Ví dụ: khi một chương trình kiểm thử và tập hợp do ứng dụng chỉ định không thành công, cho biết ứng dụng cần khởi động lại trình tự đọc-sửa đổi-ghi. (c) Sử dụng FAILED_PRECONDITION nếu máy khách không nên thử lại cho đến khi trạng thái hệ thống được khắc phục một cách rõ ràng. Ví dụ: nếu "rmdir" không thành công vì thư mục này không phải là thư mục trống, nên trả về FAILED_PRECONDITION vì ứng dụng không nên thử lại trừ khi các tệp bị xoá khỏi thư mục.

Ánh xạ HTTP: Yêu cầu không hợp lệ 400

ABORTED

Thao tác đã bị huỷ, thường là do sự cố đồng thời, chẳng hạn như lỗi kiểm tra trình tự hoặc huỷ giao dịch.

Hãy xem các nguyên tắc ở trên để quyết định giữa FAILED_PRECONDITION, ABORTEDUNAVAILABLE.

Ánh xạ HTTP: Xung đột 409

OUT_OF_RANGE

Thao tác đã được thực hiện quá phạm vi hợp lệ. Ví dụ: tìm kiếm hoặc đọc phần cuối tệp trong quá khứ.

Không giống như INVALID_ARGUMENT, lỗi này cho biết một vấn đề có thể được khắc phục nếu trạng thái hệ thống thay đổi. Ví dụ: hệ thống tệp 32 bit sẽ tạo INVALID_ARGUMENT nếu được yêu cầu đọc ở một giá trị bù không nằm trong phạm vi [0,2^32-1], nhưng hệ thống sẽ tạo OUT_OF_RANGE nếu được yêu cầu đọc từ một giá trị bù trừ vượt quá kích thước tệp hiện tại.

Có một chút trùng lặp giữa FAILED_PRECONDITIONOUT_OF_RANGE. Bạn nên sử dụng OUT_OF_RANGE (lỗi cụ thể hơn) khi áp dụng lỗi này để những phương thức gọi đang lặp lại qua một không gian có thể dễ dàng tìm lỗi OUT_OF_RANGE nhằm phát hiện thời điểm hoàn tất.

Ánh xạ HTTP: Yêu cầu không hợp lệ 400

UNIMPLEMENTED

Thao tác không được triển khai hoặc không được hỗ trợ/bật trong dịch vụ này.

Ánh xạ HTTP: 501 Chưa được triển khai

INTERNAL

Lỗi nội bộ. Tức là một số giá trị bất biến mà hệ thống cơ bản dự kiến đã bị hỏng. Mã lỗi này dành riêng cho các lỗi nghiêm trọng.

Ánh xạ HTTP: Lỗi máy chủ nội bộ 500

UNAVAILABLE

Dịch vụ này hiện không dùng được. Đây rất có thể là một tình trạng tạm thời, có thể khắc phục được bằng cách thử lại bằng thuật toán thời gian đợi. Lưu ý rằng không phải lúc nào bạn cũng có thể thử lại các thao tác không hoạt động bất biến.

Hãy xem các nguyên tắc ở trên để quyết định giữa FAILED_PRECONDITION, ABORTEDUNAVAILABLE.

Ánh xạ HTTP: Dịch vụ 503 không có sẵn

DATA_LOSS

Dữ liệu bị mất hoặc không khôi phục được.

Ánh xạ HTTP: Lỗi máy chủ nội bộ 500

Trạng thái

Loại Status xác định mô hình lỗi logic phù hợp với nhiều môi trường lập trình, bao gồm cả API REST và API RPC. Hàm này được gRPC sử dụng. Mỗi thông báo Status chứa 3 phần dữ liệu: mã lỗi, thông báo lỗi và thông tin chi tiết về lỗi.

Bạn có thể tìm hiểu thêm về mô hình lỗi này cũng như cách xử lý trong Hướng dẫn thiết kế API.

Trường
code

int32

Mã trạng thái, phải là một giá trị enum của google.rpc.Code.

message

string

Thông báo lỗi dành cho nhà phát triển, phải bằng tiếng Anh. Mọi thông báo lỗi dành cho người dùng đều phải được bản địa hoá và gửi trong trường google.rpc.Status.details hoặc để ứng dụng bản địa hoá.

details[]

Any

Danh sách các thông báo chứa thông tin chi tiết về lỗi. Có một nhóm loại thông báo phổ biến để API sử dụng.