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 หากไคลเอ็นต์ควรลองอีกครั้งในระดับที่สูงกว่า ตัวอย่างเช่น เมื่อการทดสอบและการกําหนดที่ไคลเอ็นต์ระบุไม่สําเร็จ การระบุว่าไคลเอ็นต์ควรเริ่มต้นลําดับ 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