الأخطاء

تعود الأخطاء بصيغة problem+json وفق RFC 9457. تحمل كل استجابة correlationId؛ اذكرها عند التواصل مع الدعم.

تحدد الخطة حدود المعدل

تُحسب حدود الدقيقة والساعة لأطراف الإنشاء لكل مستأجر وتحددها خطتك، كما يبين الجدول أدناه. ولأن الحد يُحسب لكل مستأجر لا لكل مفتاح، فلا يزيده مفتاح API ثانٍ. تحدد استجابة 429 النافذة التي بلغتها في ترويسة X-PDFgine-RateLimit-Scope: ‏tenant-api أو tenant-render-minute أو tenant-render-hour. للعمل الجماعي، أرسل حتى 100 مستند في طلب /document-batches واحد بدل مستند لكل طلب.

HTTP/1.1 402 Payment Required
X-PDFgine-Quota-Remaining: 0
X-PDFgine-Metering-Basis: pdf-equivalent

{
  "title": "تُجُوّزت حصة الصفحات",
  "status": 402,
  "detail": "استنفدت خطتك حصة الصفحات المتاحة.",
  "correlationId": "114249cb1dbc52a29026ab2eca5c4b72"
}

Retry-After والنافذة الزمنية

يُطبق حدان بالتتابع. يحمي الأول الخدمة ويحسب لكل بيانات اعتماد: 30 طلبات لكل نافذة دون مفتاح، و120 بمفتاح، ضمن نافذة مدتها 60 ثانية. ويأتي الثاني من خطتك ويحسب لكل مستأجر.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-PDFgine-RateLimit-Scope: tenant-render-minute

{
  "title": "Too many requests",
  "status": 429,
  "detail": "The request limit was exceeded. Please try again later.",
  "correlationId": "505aac87e234a7b4669e6203ac7ffcd5"
}

النافذة ثابتة وليست متحركة: تبدأ مع أول طلب، وتُحسب جميع الطلبات داخلها من الحد نفسه، ثم يُصفّر العداد. تشير Retry-After إلى الثواني المتبقية؛ يكفي الانتظار هذه المدة، والمحاولة قبلها تؤدي فقط إلى رفض آخر.

الأخطاء الشائعة

• تكرار طلب 4xx دون تغيير يفشل مجددًا. تعني هذه الحالات خطأ في الطلب لا انشغال الخدمة؛ تستحق 429 و5xx فقط إعادة المحاولة.
• في 429 تتضمن الاستجابة Retry-After بالفعل. تقدير الانتظار بنفسك إما يهدر الوقت أو يؤدي مباشرةً إلى رفض آخر.
• ليست 402 عطلًا يستدعي إيقاظ أحد في الثالثة صباحًا. تعني نفاد حصة الشهر؛ راقب X-PDFgine-Quota-Remaining وارفع الخطة قبل حدوث ذلك.
• لا تعني 410 عند التنزيل فقدان ملف. انتهت مدة الاحتفاظ: أُنتج المستند وحُسب ثم أُزيل وفق الجدول الذي تحدده خطتك.
• تسجيل رمز الحالة وحده يجعل طلب الدعم تخمينًا. سجّل correlationId معه؛ هذه القيمة وحدها تحدد الطلب.