Code

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

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

Enums
OK	זו לא שגיאה. הוחזרה בהצלחה. מיפוי HTTP: 200 סביר
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	השירות הזה לא זמין כרגע. סביר להניח שמדובר במצב זמני, שאפשר לתקן אותו על ידי ניסיון חוזר לאחר ניסיון חוזר. שימו לב: לא תמיד בטוח לנסות שוב פעולות שאינן חשופות. בהנחיות שלמעלה מוסבר איך בוחרים בין FAILED_PRECONDITION לבין ABORTED ו-UNAVAILABLE. מיפוי HTTP: שירות 503 לא זמין
DATA_LOSS	אובדן או שחזור של נתונים שלא ניתן לשחזר. מיפוי HTTP: שגיאת שרת פנימית 500