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

متاح فيProResearch

تحد الواجهة من عدد الطلبات التي يستطيع المفتاح والحساب إجراءها، وترد على كل رفض برمز حالة ورمز خطأ ثابت. اقرأ الرمز وليس نص الرسالة: الرمز لا يتغير.

الحدود

يُطبَّق حدّان على كل استدعاء يستخدم مفتاحًا:

• لكل مفتاح، في الساعة. لكل مفتاح حده الساعي الخاص، بسقف الحد الأقصى لخطتك.
• لكل حساب، في اليوم. تتشارك كل استدعاءات REST ميزانية يومية واحدة. اليوم بتوقيت UTC ويُعاد ضبطه عند 00:00 UTC.

أرقام كل خطة في الجدول الموجود في المفاتيح والنطاقات والحدود. لبعض المسارات حد إضافي قصير في الدقيقة: طرح سؤال (POST /ask) وبدء الرفع أو إنهاؤه يسمحان بعدد محدود من الاستدعاءات في الدقيقة.

الترويسات

كل استجابة لاستدعاء اجتاز فحص الحد الساعي تحمل:

• X-RateLimit-Limit: الحد المطبق على هذا المفتاح.
• X-RateLimit-Remaining: الاستدعاءات المتبقية في الساعة الحالية.

عند تجاوز الحد تكون الاستجابة 429 مع Retry-After، وهو عدد الثواني التي عليك انتظارها.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
Retry-After: 1260

أعد المحاولة بتأنٍّ

انتظر Retry-After من الثواني ثم حاول مجددًا. لا تعد المحاولة فورًا في حلقة. السكربت الذي يجري استدعاءات كثيرة ينبغي أن يتوقف عند بلوغ الحد اليومي ويستأنف في اليوم التالي. المثال في أمثلة يعرض دالة طلب تفعل ذلك.

يخبرك GET /rest/v2/usage بمقدار ما استهلكته من اليوم.

شكل الخطأ

يستخدم كل رفض شكل JSON واحدًا. قيمة success هي false، وتحمل error التفاصيل.

{
  "success": false,
  "error": {
    "statusCode": 403,
    "message": "This API key lacks the scope read:library.",
    "code": "SCOPE_REQUIRED",
    "details": { "scopes": ["read:library"] },
    "timestamp": "2026-11-04T09:00:00.000Z",
    "path": "/rest/v2/search",
    "method": "GET"
  }
}

code هو الجزء المقروء آليًا. قد يغيب في استجابات التحقق العادي أو "غير موجود"، حيث يحمل statusCode وmessage المعنى. وقد تكون message قائمة نصوص عندما تكون عدة حقول خاطئة.

رموز الحالة والأخطاء

الحالة	الرمز	المعنى
400	-	الطلب مشوَّه. كما أن معامل استعلام أو حقل جسم لا يعرفه المسار يُعد 400.
400	SCOPE_NOT_ALLOWED	طلبت نطاقًا لا تشمله خطتك عند إنشاء مفتاح.
401	API_KEY_INVALID	المفتاح مفقود أو غير معروف أو ملغى أو منتهي الصلاحية أو محظور. تحمل الاستجابة WWW-Authenticate: Bearer realm="readsira".
401	API_KEY_IN_QUERY	أُرسل المفتاح في العنوان. أرسله في ترويسة.
402	PLAN_REQUIRED	الخطة لا تتضمن REST API (Free)، أو لا تتضمن الرفع. تبقى مفاتيح MCP تعمل على /mcp.
402	PLAN_LIMIT_REACHED	بُلغ حد عددي، مثل الإجابات في الشهر.
402	AI_QUOTA_EXCEEDED	استُنفدت ميزانية الذكاء الاصطناعي لهذا الشهر (POST /ask).
402	PROJECT_LIMIT_REACHED	بلغ مشروع حد العناصر في خطتك.
403	SCOPE_REQUIRED	ينقص المفتاح النطاق الذي يحتاجه المسار. يذكره error.details.scopes.
404	-	غير موجود، أو ليس لك. لا تذكر الواجهة أيهما.
409	PROJECT_ARCHIVED	حاولت الكتابة إلى مشروع مؤرشف.
429	RATE_LIMITED	الحد الساعي أو اليومي. يحتوي error.details على window (hour أو day) وlimit وretryAfterSeconds.
503	AI_PAUSED	الذكاء الاصطناعي متوقف لهذا اليوم (POST /ask فقط). يستمر البحث بالعمل.

الاستجابة 429 بلا رمز تأتي من الحد القصير في الدقيقة على مسار ما. انتظر وأعد المحاولة بالطريقة نفسها.

حدود المدخلات

تفحص الواجهة كل مُدخل وترفض الطلب كله بـ 400 عندما يكون أحدها خارج النطاق.

المسار	المُدخل	المسموح
GET /search	q	من 1 إلى 500 حرف
GET /search	limit	من 1 إلى 20، والافتراضي 8
POST /ask	question	من 1 إلى 2000 حرف
POST /ask	bookmarkIds	من 1 إلى 50 معرّفًا
GET /documents/:id	offset	0 حرف أو أكثر
GET /documents/:id	maxChars	من 1 إلى 20,000، والافتراضي 12,000
GET /documents/:id/chunks	limit	من 1 إلى 100، والافتراضي 20
GET /documents/:id/transcript	limit	من 1 إلى 500
GET /projects	limit	من 1 إلى 50، والافتراضي 20
GET /projects/:id/context	q	من 1 إلى 500 حرف
GET /projects/:id/context	maxChars	من 1 إلى 32,000، والافتراضي 16,000

لكل مسار قائمة كاملة بالأنواع في مرجع REST API v2.

ذات صلة

• المصادقة ومفاتيح API
• ترقيم الصفحات
• المفاتيح والنطاقات والحدود