دليل المطوّر

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

تعتمد واجهة PollsLive حدود معدّل لكل مفتاح، وتعيد كائنات أخطاء JSON متسقة برموز مقروءة آليًا.

حدود المعدّل

تُطبَّق الحدود لكل مفتاح API (أو لكل عميل OAuth) في الدقيقة. وتجاوز الحد يعيد 429 Too Many Requests.

مجموعة نقاط النهاية	الحد	النافذة
جميع نقاط النهاية `/api/v1/`	120 طلبًا	دقيقة واحدة
`POST /api/v1/polls`	20 طلبًا (إضافةً إلى الـ120)	دقيقة واحدة لكل مفتاح
`POST /api/v1/media`	30 طلبًا	دقيقة واحدة
`GET /api/v1/polls/{id}/export?format=pdf`	10 طلبات	ساعة واحدة لكل مساحة عمل
`POST /api/oauth/token`	10 طلبات	دقيقة واحدة لكل client_id

هل تحتاج حدودًا أعلى لتكاملك؟ تواصل مع فريقنا.

عدد الجلسات المباشرة المفتوحة في آنٍ واحد سقف منفصل، لا حد لمعدّل الطلبات: Free غرفة واحدة، Pro واحدة لكل ترخيص مقدّم عرض، وPremium اثنتان. وبلوغه يعيد 403 برمز session_limit. أنهِ غرفة من Studio (أو عبر POST /api/v1/sessions/{id}/control مع end) قبل فتح أخرى.

ترويسات حد المعدّل

تحمل استجابات JSON ترويسات بيانات وصفية عن حد المعدّل:

ترويسات الاستجابة

X-RateLimit-Limit: 120
X-RateLimit-Window: 60s

تجاوز الحد يعيد 429 برمز الخطأ rate_limited. انتظر قبل إعادة المحاولة. ولا توجد ترويسة Retry-After.

صيغة استجابة الخطأ

تعيد جميع أخطاء API جسم JSON يتضمّن كائن error متداخلًا يحوي code مقروءًا آليًا وmessage مقروءة للبشر:

خطأ قياسي

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "not_found",
    "message": "Poll not found."
  }
}

أخطاء التحقّق تعيد 422 مع حقل details داخل كائن الخطأ:

خطأ تحقّق

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "details": {
      "fieldErrors": { "title": ["String must contain at least 1 character(s)"] },
      "formErrors": []
    }
  }
}

أما أخطاء رمز OAuth فتتبع صيغة RFC 6749 §5.2:

خطأ OAuth

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials."
}

رموز الأخطاء

حالة HTTP	code	المعنى
400	`invalid_json`	جسم الطلب ليس JSON صالحًا
401	`missing_authorization`	لم يُقدَّم رمز Bearer
401	`invalid_api_key`	مفتاح API غير معروف أو غير صحيح
401	`revoked_api_key`	جرى إبطال المفتاح
401	`expired_api_key`	انتهت صلاحية المفتاح بعد التدوير
401	`invalid_oauth_token`	رمز OAuth غير صالح أو منتهي الصلاحية
402	`upgrade_required`	تتطلّب العملية خطة مدفوعة (Pro فما فوق)، أو ميزة لا تشملها الخطة (مثل تصدير PDF)
403	`insufficient_scope`	لا تملك بيانات الاعتماد النطاق الذي تتطلّبه نقطة النهاية هذه
403	`session_limit`	لدى مساحة العمل بالفعل العدد المسموح لخطتها من الجلسات المباشرة المتزامنة (`POST /sessions`)
404	`not_found`	المورد غير موجود
409	`already_voted`	سبق أن صوّت voterId هذا في الاستطلاع (`POST /votes`)
409	`already_responded`	سبق أن أجاب هذا المصوّت عن الشريحة (`POST /responses`)
422	`validation_failed`	لم يجتَز جسم الطلب التحقّق من المخطّط
429	`rate_limited`	طلبات كثيرة جدًا. أعد المحاولة بعد إعادة ضبط النافذة
500	`internal_error`	خطأ غير متوقّع في الخادم

إعادة المحاولة والتراجع

نوصي باستراتيجية تراجع أسّي مع تشويش عشوائي لتكاملات الإنتاج:

إعادة المحاولة مع التراجع (JavaScript)

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options);

    if (res.status === 429) {
      // PollsLive does not send Retry-After, so back off exponentially
      // (capped at one minute, the length of a rate-limit window).
      const backoff = Math.min(1000 * 2 ** attempt + Math.random() * 500, 60000);
      await new Promise((r) => setTimeout(r, backoff));
      continue;
    }
    if (res.status >= 500 && attempt < maxRetries) {
      const backoff = Math.min(1000 * 2 ** attempt + Math.random() * 500, 30000);
      await new Promise((r) => setTimeout(r, backoff));
      continue;
    }
    return res;
  }
  throw new Error("Max retries exceeded");
}

لا تُعِد المحاولة عند أخطاء 4xx (عدا 429)، فهي تشير إلى مشكلة في طلبك لن تُحلّ بالإعادة.

صيغة أخطاء OAuth

تعيد نقطة نهاية الرمز (POST /api/oauth/token) الأخطاء بصيغة RFC 6749:

error	المعنى
`invalid_request`	معاملات ناقصة أو مشوّهة
`invalid_client`	client_id غير معروف أو client_secret خاطئ
`access_denied`	العميل مُبطَل أو محدود المعدّل (429)، أو مساحة العمل على خطة Free (402)
`unsupported_grant_type`	المدعوم هو client_credentials فقط

webhooks

api reference

هل لا تزال لديك أسئلة؟

يسعد فريقنا بمساعدتك.

تواصل معنا