אינדקס
קוד
קודי השגיאה הקנוניים של ממשקי ה-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 |
שגיאה לא ידועה. לדוגמה, השגיאה הזו יכולה להופיע כשערך מיפוי HTTP: 500 שגיאת שרת פנימית |
INVALID_ARGUMENT |
הלקוח ציין ארגומנט לא תקין. חשוב לשים לב שזה שונה מ- מיפוי HTTP: 400 Bad Request |
DEADLINE_EXCEEDED |
המועד האחרון חלף לפני שהפעולה הסתיימה. בפעולות שמשנות את מצב המערכת, יכול להיות שהשגיאה הזו תוחזר גם אם הפעולה הושלמה בהצלחה. לדוגמה, יכול להיות שתגובה מוצלחת מהשרת התעכבה מספיק זמן כדי שהמועד האחרון יחלוף. מיפוי HTTP: 504 הזמן שהוקצב לשער חלף |
NOT_FOUND |
ישות מסוימת שהתבקשה (למשל, קובץ או ספרייה) לא נמצאה. הערה למפתחי שרתים: אם בקשה נדחית עבור קבוצה שלמה של משתמשים, למשל השקה הדרגתית של תכונה או רשימת היתרים לא מתועדת, אפשר להשתמש ב- מיפוי HTTP: שגיאת 404 |
ALREADY_EXISTS |
הישות שהלקוח ניסה ליצור (למשל, קובץ או ספרייה) כבר קיימת. מיפוי HTTP: 409 Conflict |
PERMISSION_DENIED |
למבצע הקריאה אין הרשאה לבצע את הפעולה שצוינה. אסור להשתמש ב- מיפוי HTTP: 403 Forbidden |
UNAUTHENTICATED |
בבקשה אין פרטי כניסה תקפים לאימות הפעולה. מיפוי HTTP: 401 Unauthorized |
RESOURCE_EXHAUSTED |
משאב כלשהו מוצה, אולי מכסה לכל משתמש, או אולי נגמר המקום בכל מערכת הקבצים. מיפוי HTTP: 429 Too Many Requests |
FAILED_PRECONDITION |
הפעולה נדחתה כי המערכת לא במצב שנדרש לביצוע הפעולה. לדוגמה, הספרייה שרוצים למחוק לא ריקה, פעולת rmdir מופעלת על משהו שהוא לא ספרייה וכו'. מפתחי שירותים יכולים להשתמש בהנחיות הבאות כדי להחליט בין מיפוי HTTP: 400 Bad Request |
ABORTED |
הפעולה בוטלה, בדרך כלל בגלל בעיה בו-זמנית כמו כשל בבדיקת רצף או ביטול עסקה. בהנחיות שלמעלה מוסבר איך לבחור בין מיפוי HTTP: 409 Conflict |
OUT_OF_RANGE |
הפעולה בוצעה מחוץ לטווח התקין. למשל, חיפוש או קריאה מעבר לסוף הקובץ. בניגוד ל- יש חפיפה מסוימת בין מיפוי HTTP: 400 Bad Request |
UNIMPLEMENTED |
הפעולה לא מוטמעת או לא נתמכת/מופעלת בשירות הזה. מיפוי HTTP: 501 Not Implemented |
INTERNAL |
שגיאות פנימיות. המשמעות היא שחלק מהאינווריאנטים שהמערכת הבסיסית מצפה להם הופרו. קוד השגיאה הזה שמור לשגיאות חמורות. מיפוי HTTP: 500 שגיאת שרת פנימית |
UNAVAILABLE |
השירות הזה לא זמין כרגע. סביר להניח שמדובר במצב זמני, שאפשר לתקן על ידי ניסיון חוזר עם השהיה. חשוב לזכור שלא תמיד בטוח לנסות שוב פעולות שהן לא אידמפוטנטיות. בהנחיות שלמעלה מוסבר איך לבחור בין מיפוי HTTP: 503 Service Unavailable |
DATA_LOSS |
אובדן נתונים או פגיעה בנתונים שלא ניתן לשחזר. מיפוי HTTP: 500 שגיאת שרת פנימית |
סטטוס
הסוג Status מגדיר מודל שגיאה לוגי שמתאים לסביבות תכנות שונות, כולל ממשקי API בארכיטקטורת REST וממשקי API ל-RPC. הוא משמש את gRPC. כל הודעת Status מכילה שלושה נתונים: קוד שגיאה, הודעת שגיאה ופרטי שגיאה.
מידע נוסף על מודל השגיאות הזה ועל אופן העבודה איתו זמין במדריך לעיצוב API.
| שדות | |
|---|---|
code |
קוד הסטטוס, שצריך להיות ערך enum של |
message |
הודעת שגיאה שמוצגת למפתח, וצריכה להיות באנגלית. כל הודעת שגיאה שגלויה למשתמשים צריכה להיות מותאמת לשוק המקומי ולהישלח בשדה |
details[] |
רשימה של הודעות עם פרטי השגיאה. יש קבוצה נפוצה של סוגי הודעות לשימוש בממשקי API. |