שגיאות API

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

פורמט שגיאה

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

{"error":"reaction not found"}

התמקדו קודם כל בקוד המצב HTTP, ואת טקסט error השתמשו ליומנים ולרמזים למשתמש.

קודי מצב

  • 200 OK — הבקשה הצליחה, בגוף יש נתונים.
  • 201 Created — נוצר משאב חדש (חלק מ-endpoint של POST).
  • 204 No Content — הצלחה ללא גוף (חלק מהמחיקות).
  • 400 Bad Request — גוף בקשה או פרמטרים שגויים.
  • 401 Unauthorized — הטוקן חסר, שגוי או פג תוקף; או שהנתיב אינו נגיש עם טוקן אישי.
  • 402 Payment Required — הפעולה מוגבלת על ידי תוכנית או מכסה (לדוגמה, אחסון מדיה עצמי דורש premium).
  • 403 Forbidden — לטוקן חסרה ההרשאה הנדרשת לנתיב זה.
  • 404 Not Found — המשאב לא נמצא או אינו שייך לך.
  • 409 Conflict — קונפליקט מצב (לדוגמה, כפילות ערך ייחודי).
  • 422 Unprocessable Entity — הגוף תקין תחבירית אך לא עובר בדיקות עסקיות.
  • 429 Too Many Requests — חריגה ממגבלת הבקשות (ראה מגבלות).
  • 500 Internal Server Error — שגיאה פנימית בשרת; נסו שוב מאוחר יותר.

כיצד לטפל

ראו הצלחה בקודים 2xx. על 401/403 בדקו את הטוקן ואת הרשאותיו. על 4xx (חוץ מ-429) אל תחזרו על הבקשה ללא שינוי — תקנו את הבקשה. על 429 ו-5xx מתאים לנסות שוב עם השהייה אקספוננציאלית.

המשך