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 Forbidden
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	ไม่พร้อมให้บริการนี้ในขณะนี้ ซึ่งมักจะเป็นเงื่อนไขชั่วคราวที่แก้ไขได้โดยการลองอีกครั้งด้วยการหยุดชั่วคราว โปรดทราบว่าการลองดำเนินการที่ไม่ใช่แบบ Idempotent อีกครั้งอาจไม่ปลอดภัยเสมอไป ดูหลักเกณฑ์ด้านบนเพื่อเลือกระหว่าง FAILED_PRECONDITION, ABORTED และ UNAVAILABLE การแมป HTTP: 503 ไม่พร้อมให้บริการ
DATA_LOSS	ข้อมูลสูญหายโดยกู้คืนไม่ได้หรือข้อมูลเสียหาย การแมป HTTP: 500 ข้อผิดพลาดภายในเซิร์ฟเวอร์