دليل تكامل GloopAPI
معالجة الأخطاء
عالج الأخطاء وحدود إعادة المحاولة.
حدّد أولًا ما إذا قُبل الطلب، ثم قرر إعادة المحاولة. تعرض صفحات نقاط النهاية رموز الحالة الفعلية وبنية الأخطاء وأمثلة ممثلة لها. لا تشترك البروتوكولات بالضرورة في بنية JSON واحدة، وقد تُرجع الاستجابة الثنائية الناجحة JSON عند الفشل.
القرار وفق الاستجابة
| الإشارة | الخطوة التالية |
|---|---|
| 400 / حقل أو نموذج غير مدعوم | صحح المدخلات وفق schema لنقطة النهاية وكتالوج الإمكانات الحالي، ولا تكرر الطلب نفسه في حلقة |
| 401 / 403 | تحقق من صلاحية Key والحساب وIP وأذونات النموذج أو الأداة والحصة |
| 402 / الحصة غير كافية | زد الميزانية أو قلّل نطاق الطلب الجديد؛ واستمر في استعادة السجل الأصلي للمهام القائمة |
| 404 | تحقق من هوية المورد والمسار ومفاتيح التفعيل، ولا تستنتج أن الإرسال المجهول لم يُنفذ |
| 409 | ميّز بين تعارض عدم التكرار أو مهمة غير جاهزة أو عرض متغير أو مورد مستخدم بمرجع، وعالج الخطأ المحدد |
| 410 | حُذف المورد الأصلي أو انتهت صلاحيته؛ احتفظ بأدلة الحسابات وعدم التكرار ولا تنشئ مهمة أخرى تلقائيًا |
| 429 / 5xx / مهلة شبكة | بعد التراجع بسبب حد المعدل أو تعافي الخدمة، تحقق من القبول؛ إعادة الإرسال الآمنة تتطلب عقد عدم تكرار |
المقبول والمجهول
يعني HTTP 202 أن الطلب مقبول أو ما زال ينتظر الاكتمال. قد تُرجع الأداة مهمة فاشلة مع HTTP 200 أيضًا؛ اقرأ status. قبول الإلغاء لا يعني الوصول إلى حالة الإلغاء النهائية. وقد تحتوي استجابة بث HTTP 200 على أحداث خطأ أو انقطاع غير طبيعي.
عند انتهاء مهلة الإنشاء أو unknown أو billing_review احتفظ بالمفتاح الأصلي واستعلم وفق الاستعادة غير المتزامنة. إعادة الحفظ وإعادة التوليد عمليتان مختلفتان؛ وإذا انتهت صلاحية مصدر الملف فقد تظل إعادة الحفظ غير قادرة على الاستعادة.
معلومات التشخيص
سجل الوقت والطريقة والمسار وحالة HTTP ورمز الخطأ وrequest_id المتاح ومعرّف المهمة ومفتاح الطلب التجاري. أزل البيانات الحساسة ولا تسجل مفاتيح API أو الروابط الموقعة. استخدم معلومات الخطأ التي تعيدها الواجهة وسجلات الاستخدام للتشخيص.
يجب وضع حدود لعدد المحاولات التلقائية ومدتها. افحص أولًا الطلب المدفوع الذي لا يمكن إثبات عدم قبوله، ولا تجعل الإرسال المتكرر استراتيجية الاستعادة الافتراضية.
رموز أخطاء الأدوات الثابتة
| الرمز الآلي | HTTP | المعالجة الآمنة |
|---|---|---|
| invalid_input | 400 | تحقق من version وinput_schema الدقيقين وصحح مدخلات الطلب الجديد |
| invalid_cursor | 400 | لا تنشئ المؤشر بنفسك؛ حدّث الصفحة الأولى للحصول على next_cursor جديد |
| quote_required / budget_required | 400 | أضف عرض السعر أو سقف التكلفة للاستدعاء الجديد وفق حقول الإمكانات |
| quote_expired / quote_stale / invalid_quote | 409 | اطلب عرضًا جديدًا فقط بعد التحقق من أن الاستدعاء الجديد لم يُرسل؛ العروض غير الموجودة أو المملوكة للآخرين تعيد invalid_quote دون كشف الملكية |
| budget_exceeded | 409 | ميزانية الاستدعاء الجديد غير كافية؛ تحقق من maximum_usd ثم اختر الميزانية صراحةً |
| idempotency_conflict | 409 | تغيّر الطلب مع المفتاح نفسه؛ استرجع الطلب الأصلي الكامل ولا تغيّر المفتاح تلقائيًا لإعادة الإرسال |
| tool_service_unavailable | 503 | فشل البنية التحتية أو الإمكانية غير متاحة مؤقتًا؛ استعد الإرسال المجهول بالهوية والمفتاح والطلب الكامل الأصلي |
عند جهل نتيجة الإنشاء، استعلم أولًا عن run_id الأصلي. إذا لم يوجد، فأعد طلب الإنشاء الكامل باستخدام Key وIdempotency-Key الأصليين، بما في ذلك quote_id وmax_cost_usd. لا تعدّل الإرسال المجهول بسبب انتهاء العرض أو إغلاق مفتاح التفعيل. فقط العملية التجارية الجديدة المؤكد عدم قبولها يجوز لها طلب عرض جديد أو إنشاء مفتاح طلب جديد.