Code

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

บางครั้งอาจต้องใช้รหัสข้อผิดพลาดหลายรหัส บริการควรแสดงรหัสข้อผิดพลาดที่เจาะจงที่สุด เช่น ใช้ OUT_OF_RANGE มากกว่า FAILED_PRECONDITION หากใส่ทั้ง 2 รหัส ใช้ 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 ต้องห้าม
UNAUTHENTICATED	คำขอไม่มีข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ที่ถูกต้องสำหรับการดำเนินการ การแมป HTTP: 401 ไม่ได้รับอนุญาต
RESOURCE_EXHAUSTED	ทรัพยากรบางรายการใช้หมดแล้ว อาจมีโควต้าต่อผู้ใช้ หรือระบบไฟล์ทั้งหมดมีพื้นที่ไม่เพียงพอ การแมป HTTP: 429 คําขอมากเกินไป
FAILED_PRECONDITION	การดําเนินการถูกปฏิเสธเนื่องจากระบบไม่อยู่ในสถานะที่จําเป็นสําหรับการดําเนินการ เช่น ไดเรกทอรีที่จะลบจะว่างเปล่า และใช้การดําเนินการ RMdir กับไดเรกทอรีที่ไม่ใช่ข้อมูลอื่นๆ เป็นต้น ผู้ใช้บริการสามารถใช้หลักเกณฑ์ต่อไปนี้เพื่อเลือกระหว่าง FAILED_PRECONDITION, ABORTED และ UNAVAILABLE: (ก) ใช้ UNAVAILABLE หากลูกค้าสามารถลองเรียกสายที่ไม่ได้รับอีกครั้ง (ข) ใช้ ABORTED หากไคลเอ็นต์ควรลองอีกครั้งในระดับที่สูงกว่า ตัวอย่างเช่น เมื่อการทดสอบและตั้งค่าที่ระบุโดยไคลเอ็นต์ล้มเหลว การบ่งชี้ว่าไคลเอ็นต์ควรเริ่มลําดับการอ่าน-เขียน-เขียนใหม่ (ค) ใช้ 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	ไม่พร้อมให้บริการนี้ในขณะนี้ ปัญหานี้มักเป็นสภาวะชั่วคราว ซึ่งแก้ไขได้โดยการลองใหม่ด้วยระบบ Backoff โปรดทราบว่าการลองดําเนินการที่ไม่มีหลักฐานยืนยันอีกครั้งอาจไม่ปลอดภัยเสมอไป ดูหลักเกณฑ์ด้านบนสําหรับการพิจารณาระหว่างวันที่ FAILED_PRECONDITION, ABORTED และ UNAVAILABLE การแมป HTTP: บริการ 503 ไม่พร้อมใช้งาน
DATA_LOSS	ข้อมูลสูญหายหรือความเสียหายที่กู้คืนไม่ได้ การแมป HTTP: ข้อผิดพลาดภายในเซิร์ฟเวอร์ 500