טיפול בתשאול משימות CAPTCHA ובחריגות זמן

waitMs קובע כמה זמן בקשת API ממתינה לתוצאה לפני החזרת תגובה. זהו פרמטר שאילתה בכתובת ה-URL, ולא שדה ב-JSON של המשימה. ברירות המחדל ביצירה שונות בין מוצרים; לתשאול GET יש מגבלה משלו.

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

המתודה solve של ערכות ה-SDK הרשמיות יוצרת פעם אחת ומתשאלת עד לתוצאה מוכנה או לשגיאה. Python חושפת את timeout בשניות ואת poll_interval בשניות; Node.js חושפת את timeoutMs ואת pollIntervalMs באלפיות שנייה. ההגדרות המתועדות משתמשות במועד סיום לפתרון של שלוש דקות ובמרווח תשאול של שנייה אחת.

לשליטה ישירה, Python מספקת את create_task ואת get_task; Node.js מספקת את createTask ואת getTask. פעלו לפי הסדר הבא:

1. 1.

   הגדירו מועד סיום וצרו משימה אחת

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

2. 2.

   שמרו את מזהה המשימה שהוחזר ובדקו את הסטטוס שלה

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

3. 3.

   אחזרו את אותה משימה כל עוד נותר זמן

   השתמשו ב-GET /v1/tasks/:id, עם המתנה אופציונלית בתשאול ארוך של עד 15000 אלפיות שנייה. טפלו בתגובות HTTP שאינן מציינות הצלחה לפני קריאת מטען נתונים של הצלחה. אם התגובה עדיין מציינת pending או solving, חזרו על הבקשה עם אותו מזהה — ולא באמצעות יצירת משימה נוספת.

4. 4.

   עצרו במועד הסיום

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

הבקשה הזו מאחזרת משימה קיימת, עם המתנה בשרת של 15 שניות וזמן המתנה מרבי של הלקוח של 30 שניות. הגדירו את TASK_ID למזהה השמור והשאירו את SOLVETHREE_API_KEY בשרת. אף אחד מזמני ההמתנה האלה אינו מועד סיום כולל ללולאת תשאול חוזרת.

curl --fail-with-body --max-time 30 \
  "https://api.solvethree.com/v1/tasks/$TASK_ID?waitMs=15000" \
  -H "Authorization: Bearer $SOLVETHREE_API_KEY"

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

{
  "nonterminal": [
    {
      "id": "example-task",
      "status": "pending"
    },
    {
      "id": "example-task",
      "status": "solving"
    }
  ],
  "ready": {
    "id": "example-task",
    "status": "ready",
    "solution": {
      "token": "EXAMPLE_TOKEN",
      "userAgent": "EXAMPLE_USER_AGENT",
      "secChUa": "EXAMPLE_CLIENT_HINTS"
    }
  },
  "failed": {
    "id": "example-task",
    "status": "failed",
    "errorCode": "site-unreachable",
    "error": "target page did not respond"
  }
}

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

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

1. 1.

   אם יש לכם מזהה משימה, חדשו את תשאול ה-GET

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

2. 2.

   אם היצירה נקטעה, השתמשו שוב ב-requestId שלה

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

שתי ערכות ה-SDK מייצרות requestId אם הוא לא סופק, ולעולם לא מנסות שוב את היצירה באופן אוטומטי. השגיאה SolvethreeError שלהן חושפת מזהים לשחזור: request_id ו-task_id ב-Python, או requestId ו-taskId ב-JavaScript. בדקו את השדות האלה לפני שתחליטו ליצור משימה לוגית חדשה.

בקשת תשאול מחזירה שגיאת HTTP

בדקו את סטטוס ה-HTTP בנפרד מסטטוס המשימה. ApiError של ה-SDK חושפת את הסטטוס הזה ואת ההשהיה לניסיון חוזר, אם יש.

כדאי לנסות: בכשלי תשאול זמניים, כבדו את Retry-After במסגרת מועד הסיום הכולל לפתרון. שדות ה-SDK הם retry_after ב-Python, בשניות, ו-retryAfterMs ב-JavaScript, באלפיות שנייה.

המשימה מחזירה failed

קראו את errorCode ואת error; ה-SDK מייצג זאת כ-TaskFailedError.

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

האחזור מחזיר HTTP 410

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

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

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