שגיאות וטיפול בשגיאות

כשבקשה ל-Firestore במצב Datastore מצליחה, ה-API מחזיר קוד סטטוס 200 OK של HTTP יחד עם הנתונים המבוקשים בגוף התגובה.

הערה: השגיאות וקודי הסטטוס שמתוארים בדף הזה מוחזרים על ידי Datastore API ברמה נמוכה. שימו לב שספריות לקוח עשויות להחזיר את אותם ערכים או ערכים שונים.

אם בקשה נכשלת, Datastore API מחזיר קוד סטטוס HTTP‏ 4xx או 5xx שמזהה באופן כללי את הכשל, וגם תגובה שמספקת מידע ספציפי יותר על השגיאות שגרמו לכשל.

בהמשך הדף מוסבר על מבנה השגיאה, מפורטים קודי שגיאה ספציפיים ומומלץ איך לטפל בהם.

זוהי המבנה של תגובת שגיאה לבקשת JSON:

{
  "error": {
    "code": "integer",
    "message": "string",
    "status": "string"
  }
}

אובייקט התגובה מכיל שדה יחיד error שהערך שלו מכיל את הרכיבים הבאים:

רכיב	תיאור
code	קוד סטטוס של HTTP שמזהה באופן כללי את כשל הבקשה.
message	מידע ספציפי על כשל בבקשה.
status	קוד השגיאה הקנוני (google.rpc.Code) עבור Google APIs. קודי השגיאה שמוחזרים על ידי Datastore API מפורטים בקודי שגיאה.

דוגמה לתגובה לשגיאה בבקשת JSON:

{
  "error": {
    "code": 400,
    "message": "Key path is incomplete: [Person: null]",
    "status": "INVALID_ARGUMENT"
  }
}

אם בקשה שנוצרה עם סוג תוכן application/x-protobuf מובילה לשגיאה, היא תחזיר הודעת google.rpc.Status שעברה סריאליזציה כמטען ייעודי.

הערה: הטקסט שמופיע בהודעה יכול להשתנות בכל שלב, ולכן האפליקציות לא צריכות להסתמך על הטקסט בפועל.

קודי שגיאה

הדרך המומלצת לסווג שגיאות היא לבדוק את הערך של קוד השגיאה הקנוני (google.rpc.Code). בשגיאות JSON, הקוד הזה מופיע בשדה status. בשגיאות application/x-protobuf, הערך מופיע בשדה code.

קוד שגיאה קנוני	תיאור	מה מומלץ לעשות?
ABORTED	מציין שהבקשה התנגשה עם בקשה אחרת.	אם מדובר בפעולת commit לא טרנזקציונלית: מנסים לשלוח מחדש את הבקשה או משנים את מבנה הישויות כדי לצמצם את התחרות. אם מדובר בבקשות שמהוות חלק מפעולת commit טרנזקציונלית: מנסים לשלוח מחדש את כל הטרנזקציה או משנים את מבנה הישויות כדי לצמצם את התחרות.
ALREADY_EXISTS	מציין שהבקשה ניסתה להוסיף ישות שכבר קיימת.	אל תנסו שוב בלי לפתור את הבעיה.
DEADLINE_EXCEEDED	היה חריגה מהמועד האחרון בשרת.	צריך לנסות שוב באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
FAILED_PRECONDITION	מציין שאחד מהתנאים המוקדמים של הבקשה לא התקיים. בשדה ההודעה בתגובת השגיאה מופיע מידע על התנאי המוקדם שנכשל. סיבה אפשרית אחת היא הפעלת שאילתה שנדרש לה אינדקס שעדיין לא הוגדר.	אל תנסו שוב בלי לפתור את הבעיה.
INTERNAL	השרת החזיר שגיאה.	אין לנסות לשלוח את הבקשה הזו יותר מפעם אחת.
INVALID_ARGUMENT	מציין שלפרמטר של בקשה יש ערך לא תקין. בשדה ההודעה בתגובת השגיאה מפורט הערך הלא תקין.	אל תנסו שוב בלי לפתור את הבעיה.
NOT_FOUND	מציין שהבקשה ניסתה לעדכן ישות שלא קיימת.	אל תנסו שוב בלי לפתור את הבעיה.
PERMISSION_DENIED	מציין שהמשתמש לא מורשה להגיש את הבקשה.	אל תנסו שוב בלי לפתור את הבעיה.
RESOURCE_EXHAUSTED	מציין שהפרויקט חרג מהמכסה שלו או מהקיבולת של האזור או של מספר האזורים.	מוודאים שלא חרגתם מהמכסה של הפרויקט. אם חרגתם ממכסת הפרויקט, אל תנסו שוב בלי לפתור את הבעיה. אחרת, נסו שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
UNAUTHENTICATED	מציין שבבקשה לא היו פרטי כניסה תקינים לאימות.	אל תנסו שוב בלי לפתור את הבעיה.
UNAVAILABLE	השרת החזיר שגיאה.	צריך לנסות שוב באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff).