קודי סטטוס HTTP מוסברים¶
כל מי שפתח פעם כלי כמו Postman או Insomnia ושלח בקשה לשרת ראה אותם - מספרים תלת-ספרתיים שמגיעים בכל תשובה. 200, 404, 500. רוב המתחילים יודעים ש-200 טוב ו-404 רע, אבל בין לבין יש עולם שלם של קודים שכל אחד אומר משהו מדויק, ולדעת להשתמש בהם נכון זה חלק אמיתי מלבנות API טוב.
חמש המשפחות¶
קודי הסטטוס מחולקים לחמש קבוצות, לפי הספרה הראשונה. קודי 1xx הם אינפורמטיביים ונדירים לראות בפועל. קודי 2xx אומרים "הצליח" - הבקשה טופלה כמו שצריך. קודי 3xx אומרים "יש להפנות אתכם למקום אחר". קודי 4xx אומרים "יש בעיה בבקשה שלכם" - הצד הלקוח טעה במשהו. קודי 5xx אומרים "יש בעיה אצל השרת" - השרת נכשל, לא הבקשה.
ההבחנה בין 4xx ל-5xx היא לא עניין סמנטי בלבד - היא קריטית לדיבוג. קוד 4xx אומר לכם "בדקו מה שלחתם", וקוד 5xx אומר לכם "יש באג בשרת, זה לא הבעיה שלכם". מערכות ניטור רבות מוגדרות להתריע בעיקר על קודי 5xx, כי הם אלה שמעידים שמשהו אצלכם נשבר.
200 מול 201 מול 204¶
בתוך משפחת ה"הצליח", יש הבדלים חשובים. 200 OK הוא הכללי - הבקשה הצליחה, והתשובה מכילה תוכן. 201 Created מיועד ספציפית לבקשות POST שיצרו משהו חדש - כשמישהו יוצר משתמש חדש, השרת אמור להחזיר 201, לא 200, כדי לומר במפורש "יצרתי משהו". 204 No Content מיועד למקרים שהפעולה הצליחה אבל אין שום תוכן להחזיר - למשל, מחיקת רשומה, כשאין טעם להחזיר גוף תשובה ריק.
401 מול 403 - ההבדל שרוב המתחילים מבלבלים¶
זה אחד הבלבולים הנפוצים ביותר. 401 Unauthorized אומר "אני לא יודע מי אתם" - אין אימות בכלל, או שהאימות שגוי, כמו טוקן לא תקף. 403 Forbidden אומר משהו שונה לגמרי - "אני יודע בדיוק מי אתם, ואתם פשוט לא מורשים לגשת לזה". ההבדל חשוב באבטחה - החזרת 403 יכולה לחשוף למישהו שהמשאב בכלל קיים, בזמן ש-401 או אפילו 404 שקרי לפעמים משמש בכוונה כדי לא לחשוף מידע למי שלא אמור לדעת שמשהו קיים בכלל.
400 מול 422 - שגיאות בבקשה עצמה¶
400 Bad Request הוא הקוד הכללי לבקשה פגומה - JSON שבור, שדה חובה חסר. 422 Unprocessable Entity ספציפי יותר - הבקשה תקינה מבחינה טכנית וניתנת לפענוח, אבל הערכים בתוכה לא עומדים בכללי הוולידציה, כמו כתובת מייל בפורמט לא תקין. לא כל API מבחין בין השניים, אבל API מעוצב היטב כן, כי זה עוזר לצד הלקוח להבין בדיוק סוג הבעיה בלי לפרסר את הודעת השגיאה.
429 - הקוד שכולם צריכים להכיר¶
429 Too Many Requests הוא הקוד שמערכת מחזירה כשהיא חוסמת אתכם זמנית בגלל rate limiting - שלחתם יותר מדי בקשות בזמן קצר מדי. קוד זה לרוב מגיע עם header בשם Retry-After שאומר בדיוק כמה זמן לחכות לפני ניסיון נוסף - קליינטים כתובים היטב מכבדים את זה במקום פשוט לנסות שוב מיד.
למה זה חשוב מעבר לתחביר¶
בחירת קוד סטטוס נכון היא חלק מעיצוב API טוב, לא פרט טכני שולי. API שמחזיר תמיד 200 עם שדה success: false בתוכן מכריח כל צרכן שלו לפרסר את גוף התשובה כדי לדעת אם משהו הצליח, בזמן שAPI שמשתמש נכון בקודי סטטוס נותן לכל כלי סטנדרטי - דפדפנים, ספריות HTTP, מערכות ניטור - להבין מיד מה קרה בלי לגעת בתוכן בכלל.
בקורס צד-שרת שלנו אנחנו בונים APIs אמיתיים ולומדים להשתמש בקודי הסטטוס הנכונים לכל מצב, לא רק "200 כשטוב, 500 כשלא" - זה חלק מהותי מלבנות API שמפתחים אחרים ייהנו לעבוד מולו.
מתלבטים איזה קוד סטטוס מתאים למקרה ספציפי שלכם? יש בקהילה שלנו אנשים שישמחו לעזור להחליט.