Code

รหัสข้อผิดพลาดใน Canonical สําหรับ gRPC API

บางครั้งอาจมีรหัสข้อผิดพลาดหลายรายการ บริการควรแสดงรหัสข้อผิดพลาดเฉพาะที่เกี่ยวข้องมากที่สุด เช่น ใช้ OUT_OF_RANGE มากกว่า FAILED_PRECONDITION หากรหัสทั้งสองใช้ได้ เช่นเดียวกัน NOT_FOUND หรือ ALREADY_EXISTS ในช่วง FAILED_PRECONDITION

Enum
OK	ไม่ใช่ข้อผิดพลาด แสดงผลสําเร็จ การจับคู่ HTTP: 200 OK
CANCELLED	ยกเลิกการดําเนินการแล้ว โดยทั่วไปผู้โทรจะโทร การแมป HTTP: คําขอแบบไคลเอ็นต์ปิด 499
UNKNOWN	ข้อผิดพลาดที่ไม่รู้จัก เช่น ระบบอาจแสดงข้อผิดพลาดเมื่อค่า Status ที่ได้รับจากพื้นที่ที่อยู่อื่นอยู่ในพื้นที่ที่ข้อผิดพลาดซึ่งไม่ทราบในพื้นที่ของที่อยู่นี้ นอกจากนี้ ข้อผิดพลาดที่เกิดจาก API ที่ไม่แสดงผลข้อมูลข้อผิดพลาดจํานวนมากพออาจได้รับการแปลงให้เป็นข้อผิดพลาดนี้ การแมป HTTP: ข้อผิดพลาดภายในเซิร์ฟเวอร์ 500
INVALID_ARGUMENT	ไคลเอ็นต์ระบุอาร์กิวเมนต์ไม่ถูกต้อง โปรดทราบว่าเวลานี้แตกต่างจาก FAILED_PRECONDITION INVALID_ARGUMENT ระบุอาร์กิวเมนต์ที่เป็นปัญหาโดยไม่คํานึงถึงสถานะของระบบ (เช่น ชื่อไฟล์มีรูปแบบไม่ถูกต้อง) การจับคู่ HTTP: 400 คําขอไม่ถูกต้อง
DEADLINE_EXCEEDED	กําหนดเวลาหมดอายุก่อนที่การดําเนินการจะเสร็จสมบูรณ์ สําหรับการดําเนินการที่เปลี่ยนสถานะของระบบ ระบบอาจแสดงข้อผิดพลาดนี้แม้ว่าการดําเนินการจะเสร็จสมบูรณ์ก็ตาม ตัวอย่างเช่น การตอบกลับที่สําเร็จจากเซิร์ฟเวอร์อาจล่าช้าเป็นระยะเวลาที่ใกล้จะหมดอายุ การจับคู่ HTTP: 504 เกตเวย์หมดเวลา
NOT_FOUND	ไม่พบเอนทิตีที่ขอบางรายการ (เช่น ไฟล์หรือไดเรกทอรี) หมายเหตุสําหรับนักพัฒนาซอฟต์แวร์เซิร์ฟเวอร์: ถ้าคําขอถูกปฏิเสธสําหรับผู้ใช้ทั้งชั้น เช่น การเปิดตัวแบบค่อยเป็นค่อยไปหรือรายการที่อนุญาตที่ไม่มีเอกสาร อาจมีการใช้ NOT_FOUND หากคําขอถูกปฏิเสธสําหรับผู้ใช้บางรายภายในคลาส เช่น การควบคุมการเข้าถึงตามผู้ใช้ ต้องใช้ PERMISSION_DENIED การจับคู่ HTTP: ไม่พบ 404
ALREADY_EXISTS	มีเอนทิตีที่ไคลเอ็นต์พยายามจะสร้าง (เช่น ไฟล์หรือไดเรกทอรี) อยู่แล้ว การแมป HTTP: ความขัดแย้ง 409
PERMISSION_DENIED	ผู้โทรไม่มีสิทธิ์ดําเนินการที่ระบุ ต้องไม่ใช้ PERMISSION_DENIED สําหรับการปฏิเสธที่เกิดจากการใช้ทรัพยากรบางส่วนจนหมด (ใช้ RESOURCE_EXHAUSTED สําหรับข้อผิดพลาดเหล่านั้นแทน) ต้องไม่ใช้ PERMISSION_DENIED หากไม่สามารถระบุตัวผู้โทรได้ (ใช้ UNAUTHENTICATED แทนสําหรับข้อผิดพลาดเหล่านั้น) รหัสข้อผิดพลาดนี้ไม่ได้บ่งบอกว่าคําขอนั้นถูกต้องหรือมีเอนทิตีที่ขออยู่หรือตรงกับเงื่อนไขเบื้องต้นอื่นๆ การแมป HTTP: 403 Forbidden
UNAUTHENTICATED	คำขอไม่มีข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ที่ถูกต้องสำหรับการดำเนินการ การแมป HTTP: 401 ไม่ได้รับอนุญาต
RESOURCE_EXHAUSTED	ทรัพยากรบางส่วนหมดแล้ว อาจจะเป็นโควต้าต่อผู้ใช้ หรือทั้งระบบไฟล์เต็ม การจับคู่ HTTP: 429 คําขอมากเกินไป
FAILED_PRECONDITION	การดําเนินการถูกปฏิเสธเนื่องจากระบบไม่อยู่ในสถานะที่จําเป็นสําหรับการดําเนินงาน ตัวอย่างเช่น ไดเรกทอรีที่จะลบไม่ว่างเปล่า การดําเนินการ rmdir จะถูกนําไปใช้กับไดเรกทอรีที่ไม่ใช่ไดเรกทอรี ฯลฯ ผู้ใช้บริการจะใช้หลักเกณฑ์ต่อไปนี้เพื่อเลือกเวลาระหว่าง FAILED_PRECONDITION, ABORTED และ UNAVAILABLE ได้ (ก) ใช้ UNAVAILABLE หากไคลเอ็นต์ลองโทรซ้ําไม่ได้ (ข) ใช้ ABORTED หากไคลเอ็นต์ควรลองดําเนินการอีกครั้งในระดับที่สูงกว่า ตัวอย่างเช่น เมื่อการทดสอบและชุดการทํางานที่ระบุโดยไคลเอ็นต์ล้มเหลว การระบุไคลเอ็นต์ควรรีสตาร์ทลําดับ Read-modify-write (ค) ใช้ FAILED_PRECONDITION หากไคลเอ็นต์ไม่ควรลองใหม่จนกว่าสถานะของระบบจะได้รับการแก้ไขอย่างชัดแจ้ง ตัวอย่างเช่น ถ้า "rmdir" ล้มเหลวเนื่องจากไดเรกทอรีไม่ว่างเปล่า ควรส่ง FAILED_PRECONDITION กลับมาเนื่องจากไคลเอ็นต์ไม่ควรลองใหม่ นอกจากจะมีการลบไฟล์ออกจากไดเรกทอรี การจับคู่ HTTP: 400 คําขอไม่ถูกต้อง
ABORTED	การดําเนินการถูกล้มเลิก โดยทั่วไปจะเกิดจากปัญหาเกิดขึ้นพร้อมกัน เช่น การตรวจสอบของตัวตรวจสอบล้มเหลวหรือล้มเลิกธุรกรรม ดูหลักเกณฑ์ด้านบนสําหรับคําตัดสินระหว่าง FAILED_PRECONDITION, ABORTED และ UNAVAILABLE การแมป HTTP: ความขัดแย้ง 409
OUT_OF_RANGE	มีการพยายามดําเนินการหลังจากผ่านช่วงที่ถูกต้องแล้ว เช่น การค้นหาหรืออ่านไฟล์ท้ายไฟล์ ข้อผิดพลาดนี้บ่งบอกถึงปัญหาที่สามารถแก้ไขได้หากสถานะระบบเปลี่ยนไป ต่างจาก INVALID_ARGUMENT เช่น ระบบไฟล์ 32 บิตจะสร้าง INVALID_ARGUMENT หากมีการขอให้อ่านในออฟเซ็ตที่ไม่อยู่ในช่วง [0,2^32-1] แต่จะสร้าง OUT_OF_RANGE หากมีการขอให้อ่านจากออฟเซ็ตที่เกินขนาดไฟล์ปัจจุบัน มีความเหลื่อมล้ํากันเล็กน้อยระหว่าง FAILED_PRECONDITION และ OUT_OF_RANGE เราขอแนะนําให้ใช้ OUT_OF_RANGE (ข้อผิดพลาดที่เจาะจงมากขึ้น) เมื่อใช้ เพื่อที่ว่าผู้โทรที่ทําซ้ําผ่านพื้นที่ทํางานจะสามารถมองหาข้อผิดพลาด OUT_OF_RANGE ในการตรวจหาเมื่อเสร็จสิ้นได้อย่างง่ายดาย การจับคู่ HTTP: 400 คําขอไม่ถูกต้อง
UNIMPLEMENTED	การดําเนินการยังไม่เสร็จสมบูรณ์ หรือไม่สนับสนุน/เปิดใช้ในบริการนี้ การแมป HTTP: ไม่มีการใช้งาน 501
INTERNAL	ข้อผิดพลาดภายใน ซึ่งหมายความว่า ตัวแปรภายในระบบบางส่วนอาจเสียหาย รหัสข้อผิดพลาดนี้สงวนไว้สําหรับข้อผิดพลาดร้ายแรง การแมป HTTP: ข้อผิดพลาดภายในเซิร์ฟเวอร์ 500
UNAVAILABLE	ไม่พร้อมให้บริการนี้ในขณะนี้ อาการนี้มักเป็นอาการชั่วคราวซึ่งสามารถแก้ไขได้ด้วยการลองย้อนกลับ โปรดทราบว่าการลองซ้ําที่ไม่ปรากฏนั้นไม่ปลอดภัยเสมอไป ดูหลักเกณฑ์ด้านบนสําหรับคําตัดสินระหว่าง FAILED_PRECONDITION, ABORTED และ UNAVAILABLE การแมป HTTP: 503 บริการไม่พร้อมใช้งาน
DATA_LOSS	ข้อมูลสูญหายหรือกู้คืนไม่ได้ การแมป HTTP: ข้อผิดพลาดภายในเซิร์ฟเวอร์ 500