Code

קודי השגיאה הקנוניים של gRPC APIs.

לפעמים יכולים להיות כמה קודי שגיאה רלוונטיים. השירותים צריכים להחזיר את קוד השגיאה הספציפי ביותר שרלוונטי. לדוגמה, אם שני קודי השוברים חלים, המערכת תעדיף את קוד השובר OUT_OF_RANGE על פני קוד השובר FAILED_PRECONDITION. באופן דומה, עדיף להשתמש ב-NOT_FOUND או ב-ALREADY_EXISTS במקום ב-FAILED_PRECONDITION.

טיפוסים בני מנייה (enum)
OK	זו לא שגיאה, הערך הזה מוחזר אם הפעולה הצליחה. מיפוי HTTP: ‏ 200 OK
CANCELLED	הפעולה בוטלה, בדרך כלל על ידי המתקשר. מיפוי HTTP: ‏ 499 Client Closed Request
UNKNOWN	שגיאה לא ידועה. לדוגמה, יכול להיות שהשגיאה הזו תוחזר כשערך Status שמתקבל ממרחב כתובות אחר שייך למרחב שגיאות שלא מוכר במרחב הכתובות הזה. יכול להיות שגם שגיאות שמועלות על ידי ממשקי API שלא מחזירים מספיק מידע על השגיאה יומרו לשגיאה הזו. מיפוי HTTP: ‏ 500 שגיאת שרת פנימית
INVALID_ARGUMENT	הלקוח ציין ארגומנט לא חוקי. שימו לב שיש הבדל בין המאפיין הזה לבין FAILED_PRECONDITION. ‫INVALID_ARGUMENT מציין ארגומנטים בעייתיים ללא קשר למצב המערכת (למשל, שם קובץ לא תקין). מיפוי HTTP: ‏ 400 Bad Request
DEADLINE_EXCEEDED	המועד האחרון חלף לפני שהפעולה הסתיימה. בפעולות שמשנות את מצב המערכת, יכול להיות שהשגיאה הזו תוחזר גם אם הפעולה הושלמה בהצלחה. לדוגמה, יכול להיות שהתגובה המוצלחת משרת התעכבה מספיק זמן עד שתאריך היעד חלף. מיפוי HTTP: ‏ 504 Gateway Timeout
NOT_FOUND	לא נמצאה ישות מבוקשת (לדוגמה, קובץ או ספרייה). הערה למפתחי שרתים: אם בקשה נדחית עבור קבוצה שלמה של משתמשים, למשל בהשקה הדרגתית של תכונה או ברשימת היתרים לא מתועדת, אפשר להשתמש ב-NOT_FOUND. אם בקשה נדחית עבור חלק מהמשתמשים בקבוצת משתמשים, כמו בקרת גישה מבוססת-משתמש, צריך להשתמש ב-PERMISSION_DENIED. מיפוי HTTP: שגיאת 404
ALREADY_EXISTS	הישות שהלקוח ניסה ליצור (למשל, קובץ או ספרייה) כבר קיימת. מיפוי HTTP: ‏ 409 Conflict
PERMISSION_DENIED	למתקשר אין הרשאה לבצע את הפעולה שצוינה. אסור להשתמש בערך PERMISSION_DENIED לדחיות שנגרמות בגלל מיצוי של משאב מסוים (במקום זאת צריך להשתמש בערך RESOURCE_EXHAUSTED לשגיאות האלה). אסור להשתמש ב-PERMISSION_DENIED אם אי אפשר לזהות את המתקשר (במקרים כאלה צריך להשתמש ב-UNAUTHENTICATED). קוד השגיאה הזה לא מציין שהבקשה תקפה, שהישות המבוקשת קיימת או שהיא עומדת בתנאים מוקדמים אחרים. מיפוי HTTP: ‏ 403 Forbidden
UNAUTHENTICATED	בבקשה לא צוינו פרטי כניסה תקפים לאימות לצורך ביצוע הפעולה. מיפוי HTTP: ‏ 401 Unauthorized (אין הרשאה)
RESOURCE_EXHAUSTED	אזל המקום באחד המשאבים, אולי בגלל מכסת משתמשים או בגלל שמערכת הקבצים מלאה. מיפוי HTTP: ‏ 429 Too Many Requests
FAILED_PRECONDITION	הפעולה נדחתה כי המערכת לא נמצאת במצב שנדרש להפעלת הפעולה. לדוגמה, הספרייה שרוצים למחוק לא ריקה, או שפעולת rmdir מוחלת על פריט שהוא לא ספרייה וכו'. מיישמי שירות יכולים להשתמש בהנחיות הבאות כדי להחליט בין FAILED_PRECONDITION, ABORTED ו-UNAVAILABLE: (א) משתמשים ב-UNAVAILABLE אם הלקוח יכול לנסות שוב רק את הקריאה שנכשלה. ‫(ב) שימוש ב-ABORTED אם הלקוח צריך לנסות שוב ברמה גבוהה יותר. לדוגמה, כשבדיקה והגדרה שצוינו על ידי הלקוח נכשלות, מה שמצביע על כך שהלקוח צריך להפעיל מחדש רצף של קריאה, שינוי וכתיבה. ‫(ג) משתמשים ב-FAILED_PRECONDITION אם הלקוח לא צריך לנסות שוב עד שמצב המערכת תוקן באופן מפורש. לדוגמה, אם הפקודה rmdir נכשלת כי הספרייה לא ריקה, צריך להחזיר את FAILED_PRECONDITION כי הלקוח לא אמור לנסות שוב אלא אם הקבצים נמחקים מהספרייה. מיפוי HTTP: ‏ 400 Bad Request
ABORTED	הפעולה בוטלה, בדרך כלל בגלל בעיה של פעולות מקבילות, כמו כשל בבדיקת רצף או ביטול עסקה. בהנחיות שלמעלה מוסבר איך קובעים מהו השיוך המתאים ביותר מבין FAILED_PRECONDITION,‏ ABORTED ו-UNAVAILABLE. מיפוי HTTP: ‏ 409 Conflict
OUT_OF_RANGE	הניסיון לבצע את הפעולה היה אחרי הטווח התקף. לדוגמה, ניסיון לחפש או לקרוא אחרי סוף הקובץ. בשונה מ-INVALID_ARGUMENT, השגיאה הזו מצביעה על בעיה שאולי תיפתר אם מצב המערכת ישתנה. לדוגמה, אם מבקשים ממערכת קבצים של 32 ביט לקרוא נתונים בהיסט שלא נמצא בטווח [0,2^32-1], היא תיצור INVALID_ARGUMENT, אבל אם מבקשים ממנה לקרוא נתונים בהיסט שגדול מגודל הקובץ הנוכחי, היא תיצור OUT_OF_RANGE. יש חפיפה לא קטנה בין FAILED_PRECONDITION לבין OUT_OF_RANGE. מומלץ להשתמש ב-OUT_OF_RANGE (השגיאה הספציפית יותר) כשהיא רלוונטית, כדי שמשתמשים שמתקשרים למרחב יוכלו לחפש בקלות שגיאת OUT_OF_RANGE ולדעת שהם סיימו. מיפוי HTTP: ‏ 400 Bad Request
UNIMPLEMENTED	הפעולה לא יושמה או שהיא לא נתמכת או לא מופעלת בשירות הזה. מיפוי HTTP: ‏ ‎501 Not Implemented
INTERNAL	שגיאות פנימיות. המשמעות היא שחלק מהאינווריאנטים שהמערכת הבסיסית מצפה להם נשברו. קוד השגיאה הזה שמור לשגיאות חמורות. מיפוי HTTP: ‏ 500 שגיאת שרת פנימית
UNAVAILABLE	השירות הזה לא זמין כרגע. הסיבה היא כנראה מצב זמני, שאפשר לתקן אותו באמצעות ניסיון חוזר עם השהיה. חשוב לזכור שלא תמיד בטוח לנסות שוב פעולות שהן לא אידמפוטנטיות. בהנחיות שלמעלה מוסבר איך קובעים מהו השיוך המתאים ביותר מבין FAILED_PRECONDITION,‏ ABORTED ו-UNAVAILABLE. מיפוי HTTP: ‏ 503 השירות לא זמין
DATA_LOSS	פגם בנתונים או אובדן נתונים שלא ניתן לשחזר. מיפוי HTTP: ‏ 500 שגיאת שרת פנימית