Code

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

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

טיפוסים בני מנייה (enum)
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