קודי הסטטוס הבאים יכולים להופיע בתשובות של gRPC. ההנחיה הזו רלוונטית לכל הגרסאות של gRPC שמתועדות באתר הזה.
| קוד | סטטוס | הערות |
|---|---|---|
| 0 | OK |
חזרה ב-Success |
| 1 | CANCELLED |
הפעולה בוטלה, בדרך כלל על ידי מבצע הקריאה החוזרת. |
| 2 | UNKNOWN |
לדוגמה, השגיאה הזו עשויה להופיע כשערך הסטטוס שהתקבל ממרחב כתובות אחר שייך למרחב שגיאות שלא ידוע במרחב הכתובות הזה. בנוסף, שגיאות שמתקבלות מממשקי API שלא מחזירים מספיק פרטי שגיאה עשויות להפוך לשגיאה הזו. |
| 3 | INVALID_ARGUMENT |
הלקוח ציין ארגומנט לא חוקי. |
| 4 | DEADLINE_EXCEEDED |
המועד האחרון פג לפני שהפעולה הושלמה. בפעולות שמחליפות את מצב המערכת, ייתכן שהשגיאה הזו תוחזר גם אם הפעולה הושלמה בהצלחה. לדוגמה, תגובה מוצלחת משרת שהתקבלה באיחור רב, כך שפג תוקף המועד האחרון. |
| 5 | NOT_FOUND |
חלק מהישויות המבוקשות לא נמצאו. |
| 6 | ALREADY_EXISTS |
הישות שהלקוח ניסה ליצור כבר קיימת. |
| 7 | PERMISSION_DENIED |
למתקשר אין הרשאה לבצע את הפעולה שצוינה. אין להשתמש ב-PERMISSION_DENIED לדחיות שנגרמות בגלל מיצוי של משאב כלשהו. במקום זאת, צריך להשתמש ב-RESOURCE_EXHAUSTED בשביל השגיאות האלה. אין להשתמש ב-PERMISSION_DENIED אם לא ניתן לזהות את מבצע הקריאה החוזרת (במקרים כאלה, צריך להשתמש ב-UNAUTHENTICATED במקום זאת). קבלת קוד השגיאה PERMISSION_DENIED לא מעידה על כך שהבקשה תקינה, שהישות המבוקשת קיימת או שהיא עומדת בתנאים מוקדמים אחרים. |
| 8 | RESOURCE_EXHAUSTED |
משאב כלשהו אזל, אולי מכסה לכל משתמש, או אולי אין יותר מקום פנוי בכל מערכת הקבצים. |
| 9 | FAILED_PRECONDITION |
הפעולה נדחתה כי המערכת לא במצב הנדרש לביצוע הפעולה. לדוגמה, הספרייה שרוצים למחוק לא ריקה או שפעולת rmdir חלה על ספרייה שאינה ספרייה. |
| 10 | ABORTED |
הפעולה בוטלה, בדרך כלל בגלל בעיה של בו-זמניות, כמו כשל בבדיקת מאסף או ביטול עסקה. |
| 11 | OUT_OF_RANGE |
נעשו ניסיונות לבצע את הפעולה מחוץ לטווח החוקי. |
| 12 | UNIMPLEMENTED |
הפעולה לא יושמה או לא נתמכת/מופעלת בשירות הזה. |
| 13 | INTERNAL |
שגיאות פנימיות. המשמעות היא שחלק מהקבועים שלא משתנים שמצופים במערכת הבסיסית הופרו. קוד השגיאה הזה מיועד לשגיאות חמורות. |
| 14 | UNAVAILABLE |
השירות הזה לא זמין כרגע. סביר להניח שמדובר במצב זמני שאפשר לתקן אם מנסים שוב עם זמן המתנה. |
| 15 | DATA_LOSS |
אובדן נתונים או פגיעה בנתונים שלא ניתן לשחזר. |
| 16 | UNAUTHENTICATED |
בבקשה לא צוינו פרטי כניסה תקינים לביצוע הפעולה. |
לפעמים יכולים להיות כמה קודי שגיאה. השירותים צריכים להחזיר את קוד השגיאה הספציפי ביותר שרלוונטי. לדוגמה, אם שני הקודים רלוונטיים, עדיף להשתמש ב-OUT_OF_RANGE במקום ב-FAILED_PRECONDITION.
באופן דומה, עדיף להשתמש ב-NOT_FOUND או ב-ALREADY_EXISTS במקום ב-FAILED_PRECONDITION.
FAILED_PRECONDITION לעומת ABORTED לעומת UNAVAILABLE
הנה מבחן פשוט שיעזור לכם להחליט בין FAILED_PRECONDITION, ABORTED ו-UNAVAILABLE:
- משתמשים ב-
UNAVAILABLEאם הלקוח יכול לנסות שוב רק את הקריאה שנכשלה. - משתמשים ב-
ABORTEDאם הלקוח צריך לנסות שוב ברמה גבוהה יותר, למשל כשבדיקה של test-and-set שצוינה על ידי הלקוח נכשלת, מה שמציין שהלקוח צריך להפעיל מחדש רצף של קריאה, שינוי וכתיבה. - משתמשים ב-
FAILED_PRECONDITIONאם הלקוח לא צריך לנסות שוב עד שמצב המערכת מתוקן באופן מפורש. לדוגמה, אם הפקודה 'rmdir' נכשלת כי הספרייה לא ריקה, עדיף להחזיר את הערךFAILED_PRECONDITIONכי הלקוח לא צריך לנסות שוב אלא אם הקבצים נמחקים מהספרייה.
INVALID_ARGUMENT לעומת FAILED_PRECONDITION לעומת OUT_OF_RANGE
הנה מבחן פשוט שיעזור לכם להחליט בין INVALID_ARGUMENT, FAILED_PRECONDITION ו-OUT_OF_RANGE:
- משתמשים ב-
INVALID_ARGUMENTאם הארגומנטים בעייתיים ללא קשר למצב המערכת. לדוגמה: כתובת URL לא תקינה - משתמשים ב-
OUT_OF_RANGEאם ערך נמצא מחוץ לטווח בגלל מצב המערכת. לדוגמה, תאריך ההתחלה הוא לפניstart_date_restrict. - משתמשים ב-
FAILED_PRECONDITIONאם הערך לא חוקי בגלל מצב המערכת, אבל הוא לא ערךOUT_OF_RANGE.