שגיאות API של solvethree: מה לתקן ומתי לנסות שוב

טפלו בתגובות HTTP שאינן מציינות הצלחה לפני קריאת גוף תגובת הצלחה. עבור POST /v1/tasks, ‏201 מציין שנוצרה משימה חדשה; 200 מציין ששליחה חוזרת אידמפוטנטית החזירה את המשימה הקיימת. אף אחת מהתגובות לא מציינת שתהליך הפתרון הסתיים.

400 — גוף בקשה לא תקין

השוו את גוף הבקשה שנשלח לשדות ולדרישות המתועדים עבור סוג המשימה שלכם.

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

401 — מפתח API לא תקין

ודאו שהבקשה כוללת Authorization: Bearer ואחריו מפתח API תקף של סביבת העבודה.

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

402 — יתרת זכות לא מספקת

בדקו את יתרת הזכות של סביבת העבודה המשויכת למפתח ה-API.

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

403 — פרופיל אתר לא פעיל

עבור reCAPTCHA, ודאו שלאתר היעד יש פרופיל פעיל שזמין לסביבת העבודה שלכם.

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

409 — התנגשות במזהה הבקשה

בדקו אם אותו requestId כבר שימש בעבר עם נתוני קלט אחרים למשימה.

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

410 — פג תוקף התוצאה השמורה

בדקו אם אתם מאחזרים משימה שהושלמה ושהתוצאה השמורה שלה כבר אינה נשמרת.

כדאי לנסות: הפסיקו לאחזר את התוצאה הזאת. התחילו תהליך פתרון חדש אם עדיין נדרש פתרון. הסטטוס הזה מתאר את שמירת התוצאות ב-API, ולא את משך החיים של הטוקן או קובץ ה-cookie של אתר היעד.

429 — הגבלת קצב

קראו את ערך Retry-After שהוחזר בפועל בתגובה.

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

502 — שירות היצירה אינו זמין

הבחינו בין חוסר זמינות של השירות לבין קלט לא תקין או יתרה לא מספקת.

כדאי לנסות: נסו שוב מאוחר יותר. בניסיון נוסף לשלוח את אותה בקשת יצירה, השתמשו שוב במזהה הבקשה שלה ובנתוני הקלט של המשימה ללא שינוי.

HTTP 503 מציין שאין קיבולת זמינה ליצירה. נסו שוב מאוחר יותר; עבור אותה בקשת יצירה, השתמשו שוב במזהה הבקשה שלה ובנתוני הקלט של המשימה ללא שינוי.

• pending או solving: המשיכו לתשאל את המשימה הקיימת; אל תיצרו משימה חלופית רק משום שהיא עדיין לא מוכנה.
• ready: הפסיקו לתשאל וקראו את הפתרון.
• failed: הפסיקו לתשאל ובדקו את errorCode ואת error.

{
  "id": "example_login_001",
  "status": "failed",
  "errorCode": "site-unreachable",
  "error": "target page did not respond"
}

כאן, site-unreachable הוא קוד שגיאה של משימה, ולא סטטוס HTTP. בדקו את כתובת ה-URL של אתר היעד שנשלחה ואת תגובת הדף לפני שתבקשו פתרון נוסף. תשאולים נוספים לא יפעילו מחדש את המשימה שנכשלה, ושליחה חוזרת עם מזהה הבקשה המקורי שלה תחזיר את המשימה הקיימת במקום להתחיל משימה חלופית.

חריגה מזמן ההמתנה לחיבור אינה מוכיחה שיצירת המשימה נכשלה. השתמשו ב-requestId האופציונלי לפני ניסיון היצירה הראשון, כדי שתוכלו לשחזר בבטחה את אותה משימה לוגית. עליו להכיל 1–64 תווי ASCII: אותיות, ספרות, קווים תחתונים או מקפים.

1. 1.

   אם יש לכם מזהה משימה, אחזרו אותה

   השתמשו ב-GET /v1/tasks/:id וטפלו בתגובת ה-HTTP לפני בדיקת סטטוס המשימה.

2. 2.

   אם תגובת היצירה אבדה, שלחו שוב את הבקשה המקורית

   שלחו את אותם נתוני קלט של המשימה עם אותו מזהה בקשה. שליחה חוזרת אידמפוטנטית מחזירה את המשימה הקיימת אם היא נוצרה. אל תשנו את נתוני הקלט תחת אותו מזהה.

3. 3.

   צרו משימה חלופית רק כשבכוונתכם להתחיל תהליך פתרון נוסף

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

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