Code

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

לפעמים עשויים לחול כמה קודי שגיאה. השירותים צריכים להחזיר את קוד השגיאה הספציפי ביותר שחל. לדוגמה, עדיף להשתמש ב-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
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 Unauthorized
RESOURCE_EXHAUSTED	חלק מהמשאבים אזלו, אולי מכסה לכל משתמש, או אולי אין מספיק מקום במערכת הקבצים כולה. מיפוי HTTP: 429 בקשות רבות מדי
FAILED_PRECONDITION	הפעולה נדחתה כי המערכת לא במצב שנדרש לביצוע הפעולה. לדוגמה, הספרייה שרוצים למחוק לא ריקה, פעולת rmdir חלה על ספרייה שאינה ספרייה וכו'. מטמיעי שירותים יכולים להשתמש בהנחיות הבאות כדי להחליט בין FAILED_PRECONDITION, ABORTED ו-UNAVAILABLE: (א) אפשר להשתמש ב-UNAVAILABLE אם הלקוח יכול לנסות שוב רק את הקריאה שנכשלה. (ב) אם הלקוח צריך לנסות שוב ברמה גבוהה יותר, צריך להשתמש ב-ABORTED. לדוגמה, כשפעולת בדיקה והגדרה בהגדרת הלקוח נכשלת, המשמעות היא שהלקוח צריך להפעיל מחדש רצף של קריאה-שינוי-כתיבה. (ג) צריך להשתמש ב-FAILED_PRECONDITION אם הלקוח לא צריך לנסות שוב עד שמצב המערכת יתוקן באופן מפורש. לדוגמה, אם הפרמטר 'rmdir' נכשל כי הספרייה לא ריקה, לכן צריך להחזיר את FAILED_PRECONDITION כי הלקוח לא צריך לנסות שוב, אלא אם הקבצים נמחקים מהספרייה. מיפוי HTTP: 400 Bad Request
ABORTED	הפעולה בוטלה, בדרך כלל עקב בעיה בו-זמניות (concurrency) כגון כשל בבדיקת רצף או ביטול עסקה. ההנחיות שלמעלה יעזרו לך להחליט בין 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 Bad Request
UNIMPLEMENTED	הפעולה לא יושמה או אינה נתמכת/מופעלת בשירות זה. מיפוי HTTP: 501 לא מיושם
INTERNAL	שגיאות פנימיות. המשמעות היא שחלק מהמשתנים הקבועים הצפויים על ידי המערכת הבסיסית מנותקים. קוד השגיאה הזה שמור לשגיאות חמורות. מיפוי HTTP: שגיאת שרת פנימית 500
UNAVAILABLE	השירות הזה לא זמין כרגע. סביר להניח שמדובר במצב זמני, וניתן לתקן אותו באמצעות ניסיון חוזר עם השהיה לפני ניסיון חוזר (backoff). שימו לב שלא תמיד בטוח לבצע ניסיון חוזר של פעולות שהן לא אידמפוטנטיות. ההנחיות שלמעלה יעזרו לך להחליט בין FAILED_PRECONDITION, ABORTED ו-UNAVAILABLE. מיפוי HTTP: 503 Service Unavailable
DATA_LOSS	אובדן או השחתה של נתונים שלא ניתן לשחזר. מיפוי HTTP: שגיאת שרת פנימית 500