Package google.rpc

אינדקס

• Code (enum)

קוד

קודי השגיאה הקנוניים של 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 אם הלקוח צריך לנסות שוב ברמה גבוהה יותר. לדוגמה, כשבדיקה והגדרה שצוינו על ידי הלקוח נכשלות, מה שמצביע על כך שהלקוח צריך להפעיל מחדש רצף של קריאה, שינוי וכתיבה. ‫(c) משתמשים ב-FAILED_PRECONDITION אם הלקוח לא צריך לנסות שוב עד שמצב המערכת יתוקן באופן מפורש. לדוגמה, אם הפקודה rmdir נכשלת כי הספרייה לא ריקה, צריך להחזיר את FAILED_PRECONDITION כי הלקוח לא צריך לנסות שוב אלא אם הקבצים נמחקים מהספרייה. מיפוי HTTP: ‏ 400 Bad Request
ABORTED	הפעולה בוטלה, בדרך כלל בגלל בעיה של בו-זמניות (concurrency), כמו כשל בבדיקת רצף או ביטול טרנזקציה. בהנחיות שלמעלה מוסבר איך קובעים מהו השיוך המתאים ביותר מבין 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 שגיאת שרת פנימית