أخطاء API في solvethree: ما الذي يجب إصلاحه ومتى تعيد المحاولة؟

عالج استجابات HTTP غير الناجحة قبل قراءة حمولة النجاح. بالنسبة إلى POST /v1/tasks، تعني 201 إنشاء مهمة جديدة؛ وتعني 200 أن إعادة إرسال الطلب دون تكرار الأثر أعادت المهمة الموجودة. ولا تعني أيٌّ من الاستجابتين اكتمال عملية الحل.

400 — جسم الطلب غير صالح

قارن جسم الطلب المُرسل بالحقول والمتطلبات الموثّقة لنوع مهمتك.

جرّب هذا: صحّح المدخلات قبل الإرسال مجدداً. لن تؤدي إعادة إرسال جسم طلب غير صالح دون تغيير إلى إصلاحه. استخدم مواصفات إنشاء المهام للتحقّق من الطلب.

401 — مفتاح API غير صالح

تحقّق من أن الطلب يتضمن Authorization: Bearer متبوعاً بمفتاح API صالح لمساحة العمل.

جرّب هذا: أضف المفتاح المفقود أو صحّح المفتاح المرفوض. احتفظ به على الخادم بدلاً من كشفه في شيفرة المتصفح.

402 — الرصيد غير كافٍ

تحقّق من رصيد مساحة العمل المرتبطة بمفتاح API.

جرّب هذا: أضف رصيداً إلى مساحة العمل تلك قبل إعادة المحاولة. لا تتعامل مع أخطاء HTTP أو حالات فشل المهام غير المرتبطة بالرصيد على أنها مشكلات رصيد.

403 — ملف تعريف الموقع غير نشط

بالنسبة إلى reCAPTCHA، تأكّد من أن الموقع المستهدف لديه ملف تعريف نشط متاح لمساحة عملك.

جرّب هذا: أعدّ الموقع المستهدف في وحدة التحكم وتأكّد من أن ملف التعريف نشط. إن تضمين اسم مضيف وإجراء في المهمة لا يُنشئ ملف تعريف. واستجابة البوابة هذه ليست دليلاً على أن الموقع المستهدف حظرك.

409 — تعارض في معرّف الطلب

تحقّق مما إذا كان requestId نفسه قد استُخدم سابقاً مع مدخلات مهمة مختلفة.

جرّب هذا: استخدم المدخلات الأصلية لاستعادة المهمة الأصلية. وإذا كنت تنوي إنشاء مهمة مختلفة، فامنحها معرّف طلب جديداً.

410 — انتهت صلاحية النتيجة المخزّنة

تحقّق مما إذا كنت تجلب مهمة مكتملة لم يعد يُحتفظ بنتيجتها المخزّنة.

جرّب هذا: توقّف عن جلب تلك النتيجة. ابدأ عملية حل جديدة إذا كنت لا تزال تحتاج إليها. تصف هذه الحالة مدة احتفاظ API بالنتائج، لا مدة صلاحية الرمز أو ملف تعريف الارتباط لدى الموقع المستهدف.

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.

   لا تُنشئ بديلاً إلا إذا كنت تقصد بدء عملية حل أخرى

   يمثّل معرّف الطلب الجديد عملاً جديداً، لا استعادة للطلب السابق. استخدمه عن قصد، مثلاً بعد فحص فشل نهائي واتخاذ قرار بإعادة المحاولة.

راجع الاستعادة باستخدام معرّف الطلب لمعرفة كيفية التعامل مع إعادة الإرسال، أو الاستقصاء والمهل الزمنية عندما ينجح الإنشاء وتظل المهمة قيد التنفيذ.