الأخطاء والحدود

استجابات الأخطاء

تستخدم الأخطاء رموز حالة HTTP المعتادة مع جسم JSON يصف المشكلة. وإلى جانب الرسالة المقروءة message، يحمل معظمها رمزًا ثابتًا code — اعتمد على code في التفريع، لا على نص الرسالة:

الخطأ 400 الناتج عن خريطة values خاطئة يخبرك بالضبط أي مفتاح تصلحه — إذ تقتبس الرسالة التسمية المقروءة التي يعرضها القالب، ويعطي details المفتاح الذي يستخدمه جسم طلبك:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "\"Client Name\" is required",
  "code": "invalid_values",
  "details": [{ "key": "client_name", "label": "Client Name", "reason": "is required" }]
}

حدّ المعدّل

يسري حدّان، ويُطبَّق الأضيق منهما:

• 120 طلبًا في الدقيقة لكل عنوان IP — يتقاسمه كل ما يتصل من ذلك العنوان، بما في ذلك بقية حركة الشبكة لديك.
• 600 طلب في الدقيقة لكل مفتاح واجهة — ميزانية تكاملك وحده.

ويُبلَّغ عن كليهما عبر الترويسات x-ratelimit-limit وx-ratelimit-remaining وx-ratelimit-reset (الثواني المتبقية حتى تُجدَّد النافذة)، كما يحمل الرد 429 ترويسة retry-after. وإن كنت تستطلع حالة عدد كبير من طلبات التوقيع، فوزّع الاستطلاعات بدل إرسالها دفعةً واحدة — أو اسردها في نداء واحد عبر GET /esign/submissions.

الحصة الشهرية لطلبات التوقيع

إرسال طلب توقيع — من التطبيق أو عبر الواجهة — يُحتسَب من الحصة الشهرية لمساحة عملك، وهي تُجدَّد في بداية كل شهر ميلادي (بتوقيت UTC):

وحين تُستنفَد الحصة، يعيد POST /esign/submissions رمز 403 مع code: limit_reached (والرسالة limit_reached:signatureRequests)، حاملًا الحد limit والمقدار المستهلك used. أما سرد القوالب واستطلاع الحالة وقراءة الاستهلاك وتنزيل المستندات الموقّعة فلا تُحتسَب أبدًا، والطلب المعاد بمفتاح idempotencyKey مستخدَم سابقًا لا يُحتسَب مرة أخرى.

وبدل أن تكتشف السقف عبر إرسال فاشل، اقرأ GET /esign/usage قبل أي دفعة.