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