Code

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

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

Enums
OK	זו לא שגיאה. הוחזרה בהצלחה. מיפוי HTTP: 200 OK
CANCELLED	הפעולה בוטלה, בדרך כלל על ידי המתקשר. מיפוי HTTP: בקשה לסגירת לקוח 499
UNKNOWN	שגיאה לא ידועה. לדוגמה, ייתכן שהשגיאה הזו מוחזרת כאשר ערך של Status שמתקבל ממרחב כתובות אחר שייך למרחב שגיאה שלא ידוע במרחב הכתובות הזה. כמו כן, ייתכן שהמערכת תמיר את השגיאות שהועלו על ידי ממשקי API שלא מחזירים מספיק מידע על השגיאות. מיפוי HTTP: שגיאת שרת פנימית 500
INVALID_ARGUMENT	הלקוח ציין ארגומנט לא חוקי. חשוב לשים לב שהנתון הזה שונה מFAILED_PRECONDITION. המאפיין INVALID_ARGUMENT מציין ארגומנטים שבעייתיים, ללא קשר למצב המערכת (למשל, שם קובץ בפורמט שגוי). מיפוי HTTP: בקשה שגויה של 400
DEADLINE_EXCEEDED	המועד האחרון חלף לפני שניתן היה להשלים את הפעולה. עבור פעולות שמשנות את מצב המערכת, ייתכן שתוחזר השגיאה הזו גם אם הפעולה הושלמה בהצלחה. לדוגמה, תגובה מוצלחת משרת מסוים עשויה להתעכב מספיק זמן כדי שתאריך היעד יפוג. מיפוי HTTP: זמן קצוב לתפוגה של 504 Gateway
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	הפעולה נדחתה מכיוון שהמערכת אינה במצב הדרוש לביצוע הפעולה. לדוגמה, הספרייה שיש למחוק אינה ריקה, פעולת RMID מתבצעת על תיקייה שאינה ספרייה וכו'. ספקי השירות יכולים להיעזר בהנחיות הבאות כדי להחליט בין 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