שגיאות API: מה כדאי לנסות שוב ומה יחזור בדיוק אותו דבר

שמונה קודי שגיאה, ורק שלושה מהם שווים ניסיון חוזר.

429 הוא חריגה ממגבלת קצב. 500 ו-529 הם תקלה או עומס בצד השרת. שלושתם חולפים. כל השאר, 400, 401, 403, 404 ו-413, יחזרו בדיוק אותו דבר בניסיון הבא, כי הבעיה בבקשה עצמה.

למה תפיסה אחת רחבה זו טעות

הדפוס הנפוץ הוא בלוק אחד שתופס את מחלקת השגיאה הבסיסית ומדפיס הודעה. הוא עובד, ובדיוק בגלל זה הוא מסתיר את ההבדל.

ה-SDK מגדירים מחלקת חריגה נפרדת לכל קוד סטטוס. זה נעשה כדי שאפשר יהיה להבדיל. שרשרת תפיסה שמסודרת מהספציפי לכללי, למשל לא נמצא, ואז מגבלת קצב, ואז שגיאת סטטוס כללית, ואז שגיאת חיבור, נותנת התנהגות שונה לכל מקרה.

בדיקה של הודעת השגיאה כמחרוזת היא דרך גרועה עוד יותר. ההודעות משתנות.

מה כל אחד באמת אומר

400 הוא בקשה שגויה, ובדרך כלל אחת מארבע: JSON פגום, פרמטר חובה חסר, תפקידים שלא מתחלפים בין משתמש לעוזר, או פרמטר שהוסר במודל הזה. הקטגוריה האחרונה תפסה הרבה אנשים בהעברה בין דורות, כי temperature ו-budget_tokens עברו מלהיות תקינים לשגיאה.

401 הוא מפתח לא תקין או חסר. יש מקרה מבלבל: אסימון OAuth שנשלח בכותרת של מפתח API במקום בכותרת ההרשאה נותן 401 שנראה כמו מפתח שגוי.

404 הוא לרוב שגיאת כתיב במזהה המודל, או מודל שהוצא משימוש.

413 הוא בקשה גדולה מדי. הפתרון הוא לקצץ היסטוריה או לפצל מסמכים, לא לנסות שוב.

ניסיון חוזר

ה-SDK כבר מנסים שוב אוטומטית על 408, 409, 429, שגיאות שרת ותקלות חיבור. ברירת המחדל היא שני ניסיונות, עם נסיגה מעריכה.

זה אומר שני דברים. ראשית, קוד שמוסיף לולאת ניסיון משלו מכפיל את מה שכבר קורה. שנית, פסק זמן הוא מוכפל: זמן הקיר המקסימלי הוא הפסק כפול מספר הניסיונות ועוד אחד. מי שמגדיר פסק זמן של דקה ומצפה שהקריאה תיגמר תוך דקה יופתע.

בתשובת 429 יש כותרת שאומרת כמה שניות להמתין, וכותרות נוספות עם המכסה שנותרה. כדאי לקרוא אותן ולא לנחש.

שדה שכדאי להכיר

לכל שגיאת סטטוס יש שדה סוג שמחזיר מחרוזת כמו שגיאת הרשאה או שגיאת חיוב. הוא מאפשר הבחנה עדינה יותר מקוד הסטטוס, למשל בין בעיית חיוב לבעיית הרשאה, ששתיהן חוזרות כ-403.

המקרה שאינו שגיאה בכלל

תשובה עם סיבת עצירה של סירוב חוזרת עם קוד 200 תקין. המסננים סירבו לבקשה, ולכן התוכן ריק או חלקי, אבל שום דבר בשכבת ה-HTTP לא מסמן את זה.

קוד שקורא את האיבר הראשון בתוכן בלי לבדוק את סיבת העצירה קורס שם, וזו קריסה שקשה לאתר כי היא לא נראית בלוגים של שגיאות. הבדיקה של סיבת העצירה צריכה להיות לפני קריאת התוכן, לא אחריה.