الأخطاء
تعود الأخطاء بصيغة JSON مع رمز حالة HTTP. ويخبرك الرمز هل ينبغي تصحيح الطلب أم يكفي أن تعيد المحاولة.
صيغة الخطأ
HTTP/1.1 400 Bad Request
Content-Type: application/json
{ "success": false, "error": "header/footer requires a margin large enough to hold them" }تحقّق دائمًا من رمز الحالة قبل حفظ جسم الاستجابة: استجابة الخطأ تكون JSON، لا ملف PDF ولا صورة. رسائل الخطأ باللغة الإنجليزية.
رموز الحالة
| الرمز | المعنى | ما العمل | إعادة المحاولة؟ |
|---|---|---|---|
200 | نجاح. جسم الاستجابة هو الملف، أو JSON مع encode أو response_type=json. | لا شيء. | – |
400 | الطلب غير صالح: قيمة معامل خاطئة، أو إرسال url و html معًا أو عدم إرسال أي منهما، أو عنوان محجوب، أو خيار غير مدعوم، أو تعذّر تحميل الصفحة. | اقرأ رسالة error وصحّح الطلب. | لا |
401 | مفتاح الواجهة البرمجية مفقود أو غير صالح. | تحقّق من طريقة إرسال المفتاح؛ راجع المصادقة. | لا |
404 | لم يطابق selector أي عنصر في الصفحة. | تحقّق من المحدِّد، أو انتظر العنصر عبر wait_for_selector. | لا |
408 | استغرق الإنشاء أكثر من المهلة (30 ثانية كحد أقصى). | خفّف الصفحة، واحجب الإعلانات وأدوات التتبع، أو استخدم wait_until=load بدل networkidle. | مرة واحدة ربما |
413 | جسم الطلب أكبر من 10 ميغابايت. | حمّل الصور الكبيرة من عناوينها بدل تضمينها، أو اضغطها. | لا |
429 | قائمة انتظار الإنشاء ممتلئة في هذه اللحظة. | انتظر وأعد المحاولة مع زيادة مدة الانتظار تدريجيًا. | نعم |
500 | خطأ غير متوقع أثناء الإنشاء. | أعد المحاولة مرة واحدة؛ وإن تكرر فراسل الدعم مع وقت الطلب. | مرة واحدة |
502 و 503 | الخدمة تُعاد تشغيلها، أو أحد مكوناتها غير متاح لحظيًا. | أعد المحاولة مع زيادة مدة الانتظار تدريجيًا. | نعم |
رسائل شائعة
| الرسالة | السبب |
|---|---|
The source URL points to a blocked or unresolvable address | العنوان خاص أو محلي أو عنوان بيانات وصفية للسحابة، أو لا يمكن حلّ نطاقه. |
Could not load the source: net::ERR_... | تعذّر الوصول إلى الصفحة من جدة: عنوان خاطئ، أو الموقع متوقف، أو يرفض الاتصال. |
The source URL returned HTTP 404 | فقط مع raise_for_status: الصفحة نفسها ردّت بخطأ. |
header/footer requires a margin ... | أُرسلت ترويسة أو تذييل دون margin. |
Not supported: ... never stored | أُرسل خيار يخزّن الملف (webhook أو store أو s3_destination وما شابهها). |
selector and full_page cannot be combined | اختر أحدهما. |
body must be object | جسم الطلب ليس JSON. أرسل Content-Type: application/json مع كائن JSON. |
Rendering timed out ... | راجع الرمز 408 أعلاه. |
إعادة المحاولة بأمان
ليس لطلبات الإنشاء أي آثار جانبية، لذا لا تُنتج إعادة المحاولة أي تكرار. أعد المحاولة عند 429 و 502 و 503 مع انتظار متزايد (مثلًا 2 ثم 4 ثم 8 ثوانٍ)، والتزم بترويسة Retry-After حين توجد. ولا تُعِد المحاولة عند أخطاء 4xx الأخرى غير 408 و 429، فستفشل مرة أخرى. تجد حلقات إعادة محاولة جاهزة في الأمثلة البرمجية.