NueForm

حدود الطلبات

فهم حدود طلبات واجهة برمجة تطبيقات NueForm وكيفية مراقبة استخدامك من خلال ترويسات الاستجابة وأفضل الممارسات للبقاء ضمن حصتك.

تفرض واجهة برمجة تطبيقات NueForm حدودًا على الطلبات لضمان الاستخدام العادل واستقرار المنصة. يتم تطبيق الحدود لكل حساب مستخدم باستخدام نافذة منزلقة مدتها 60 ثانية.

الحدود حسب الخطة

الخطةالطلبات في الدقيقةالنافذة
Pro10060 ثانية (منزلقة)
Enterprise50060 ثانية (منزلقة)

يتم تطبيق حدود الطلبات على مستوى الحساب وليس لكل مفتاح API. إذا كان لديك مفاتيح متعددة، فإنها تتشارك نفس حصة حدود الطلبات.

ترويسات حدود الطلبات

تتضمن كل استجابة API ترويسات حدود الطلبات حتى تتمكن من مراقبة استخدامك في الوقت الفعلي:

الترويسةالوصفمثال
X-RateLimit-Limitالحد الأقصى للطلبات المسموح بها لكل نافذة100
X-RateLimit-Remainingالطلبات المتبقية في النافذة الحالية87
X-RateLimit-Resetطابع زمني ISO 8601 عند إعادة تعيين النافذة2026-02-28T14:30:45.000Z

مثال على ترويسات الاستجابة:

text
HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 2026-02-28T14:30:45.000Z

عند تجاوز حد الطلبات

إذا تجاوزت حد الطلبات، تُرجع الواجهة البرمجية استجابة 429 Too Many Requests. تتضمن الاستجابة ترويسات حدود الطلبات القياسية بالإضافة إلى ترويسة Retry-After تشير إلى عدد الثواني للانتظار قبل إعادة المحاولة.

الاستجابة

json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please try again later.",
    "status": 429
  }
}

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

text
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-02-28T14:31:12.000Z
Retry-After: 27

قيمة Retry-After هي عدد الثواني حتى ينتهي صلاحية أقدم طلب في نافذتك الحالية وتتحرر السعة.

مراقبة الاستخدام

استخدم ترويسات حدود الطلبات بشكل استباقي لتجنب الوصول إلى الحد:

JavaScript

javascript
async function callApi(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  // Log rate limit status
  const remaining = response.headers.get("X-RateLimit-Remaining");
  const limit = response.headers.get("X-RateLimit-Limit");
  console.log(`Rate limit: ${remaining}/${limit} remaining`);

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get("Retry-After"), 10);
    console.warn(`Rate limited. Retrying in ${retryAfter} seconds...`);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    return callApi(url, options); // Retry
  }

  return response;
}

Python

python
import os
import time
import requests

API_KEY = os.environ["NUEFORM_API_KEY"]
BASE_URL = "https://app.nueform.com/api/v1"

def call_api(path, method="GET", **kwargs):
    url = f"{BASE_URL}{path}"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }

    response = requests.request(method, url, headers=headers, **kwargs)

    # Log rate limit status
    remaining = response.headers.get("X-RateLimit-Remaining")
    limit = response.headers.get("X-RateLimit-Limit")
    print(f"Rate limit: {remaining}/{limit} remaining")

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 5))
        print(f"Rate limited. Retrying in {retry_after} seconds...")
        time.sleep(retry_after)
        return call_api(path, method, **kwargs)  # Retry

    return response

أفضل الممارسات

نفّذ التراجع الأسّي

عند تلقي استجابة 429، استخدم التراجع الأسّي بدلاً من إعادة المحاولة فورًا. ابدأ بقيمة Retry-After وزِد التأخير مع كل محاولة إعادة لاحقة.

javascript
async function fetchWithBackoff(url, options = {}, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, {
      ...options,
      headers: {
        "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
        "Content-Type": "application/json",
        ...options.headers,
      },
    });

    if (response.status !== 429) {
      return response;
    }

    if (attempt === maxRetries) {
      throw new Error("Max retries exceeded due to rate limiting");
    }

    const retryAfter = parseInt(
      response.headers.get("Retry-After") || "5",
      10
    );
    const backoff = retryAfter * Math.pow(2, attempt);
    console.warn(`Rate limited. Retry attempt ${attempt + 1} in ${backoff}s`);
    await new Promise((resolve) => setTimeout(resolve, backoff * 1000));
  }
}

خزّن الاستجابات مؤقتًا

تجنب إجراء استدعاءات API متكررة عن طريق تخزين الاستجابات محليًا. تعريفات النماذج وتكوينات السمات لا تتغير كثيرًا وهي مرشحة جيدة للتخزين المؤقت.

javascript
const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedForm(formId) {
  const cacheKey = `form_${formId}`;
  const cached = cache.get(cacheKey);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const response = await fetch(
    `https://app.nueform.com/api/v1/forms/${formId}`,
    {
      headers: {
        "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
      },
    }
  );

  const { data } = await response.json();
  cache.set(cacheKey, { data, timestamp: Date.now() });
  return data;
}

استخدم webhooks للبيانات في الوقت الفعلي

بدلاً من استطلاع الواجهة البرمجية للحصول على ردود نماذج جديدة، قم بإعداد webhooks لتلقي الإشعارات عند وصول الإرسالات. هذا يلغي طلبات الاستطلاع المتكررة ويوصل البيانات بشكل أسرع.

اجمع العمليات عند الإمكان

إذا كنت بحاجة إلى استرداد موارد متعددة، استخدم نقاط نهاية القوائم مع التصفح بدلاً من إجراء طلبات فردية لكل مورد. استدعاء واحد لـ

GET/api/v1/forms?per_page=100
أكثر كفاءة بكثير من 100 استدعاء منفصل.

راقب ترويسة X-RateLimit-Remaining

تتبع حصتك المتبقية وقلّل سرعة طلباتك قبل الوصول إلى الحد. إذا انخفض X-RateLimit-Remaining إلى أقل من 10، فكّر في إضافة تأخير قصير بين الطلبات.

تحمي حدود الطلبات المنصة لجميع المستخدمين. التطبيقات التي تتجاوز حدود الطلبات باستمرار أو تحاول التحايل عليها قد يتم تعليق وصولها إلى API. إذا كنت بحاجة إلى حدود أعلى، فكّر في الترقية إلى خطة Enterprise أو التواصل مع الدعم.

ترقية حد الطلبات الخاص بك

إذا كنت بحاجة إلى أكثر من 100 طلب في الدقيقة، قم بالترقية إلى خطة Enterprise للحصول على 500 طلب في الدقيقة. لحدود تتجاوز Enterprise، تواصل مع فريق المبيعات لمناقشة ترتيبات مخصصة.

الخطةحد الطلباتالسعر
Pro100 طلب/دقيقة$29/شهر
Enterprise500 طلب/دقيقة$99/شهر
مخصصقابل للتفاوضتواصل مع المبيعات
آخر تحديث: 6 أبريل 2026