تفرض واجهة برمجة تطبيقات NueForm حدودًا على الطلبات لضمان الاستخدام العادل واستقرار المنصة. يتم تطبيق الحدود لكل حساب مستخدم باستخدام نافذة منزلقة مدتها 60 ثانية.
الحدود حسب الخطة
| الخطة | الطلبات في الدقيقة | النافذة |
|---|---|---|
| Pro | 100 | 60 ثانية (منزلقة) |
| Enterprise | 500 | 60 ثانية (منزلقة) |
يتم تطبيق حدود الطلبات على مستوى الحساب وليس لكل مفتاح API. إذا كان لديك مفاتيح متعددة، فإنها تتشارك نفس حصة حدود الطلبات.
ترويسات حدود الطلبات
تتضمن كل استجابة API ترويسات حدود الطلبات حتى تتمكن من مراقبة استخدامك في الوقت الفعلي:
| الترويسة | الوصف | مثال |
|---|---|---|
X-RateLimit-Limit | الحد الأقصى للطلبات المسموح بها لكل نافذة | 100 |
X-RateLimit-Remaining | الطلبات المتبقية في النافذة الحالية | 87 |
X-RateLimit-Reset | طابع زمني ISO 8601 عند إعادة تعيين النافذة | 2026-02-28T14:30:45.000Z |
مثال على ترويسات الاستجابة:
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 تشير إلى عدد الثواني للانتظار قبل إعادة المحاولة.
الاستجابة
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Please try again later.",
"status": 429
}
}
ترويسات استجابة 429
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
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
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 وزِد التأخير مع كل محاولة إعادة لاحقة.
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 متكررة عن طريق تخزين الاستجابات محليًا. تعريفات النماذج وتكوينات السمات لا تتغير كثيرًا وهي مرشحة جيدة للتخزين المؤقت.
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 لتلقي الإشعارات عند وصول الإرسالات. هذا يلغي طلبات الاستطلاع المتكررة ويوصل البيانات بشكل أسرع.
اجمع العمليات عند الإمكان
إذا كنت بحاجة إلى استرداد موارد متعددة، استخدم نقاط نهاية القوائم مع التصفح بدلاً من إجراء طلبات فردية لكل مورد. استدعاء واحد لـ
/api/v1/forms?per_page=100راقب ترويسة X-RateLimit-Remaining
تتبع حصتك المتبقية وقلّل سرعة طلباتك قبل الوصول إلى الحد. إذا انخفض X-RateLimit-Remaining إلى أقل من 10، فكّر في إضافة تأخير قصير بين الطلبات.
تحمي حدود الطلبات المنصة لجميع المستخدمين. التطبيقات التي تتجاوز حدود الطلبات باستمرار أو تحاول التحايل عليها قد يتم تعليق وصولها إلى API. إذا كنت بحاجة إلى حدود أعلى، فكّر في الترقية إلى خطة Enterprise أو التواصل مع الدعم.
ترقية حد الطلبات الخاص بك
إذا كنت بحاجة إلى أكثر من 100 طلب في الدقيقة، قم بالترقية إلى خطة Enterprise للحصول على 500 طلب في الدقيقة. لحدود تتجاوز Enterprise، تواصل مع فريق المبيعات لمناقشة ترتيبات مخصصة.
| الخطة | حد الطلبات | السعر |
|---|---|---|
| Pro | 100 طلب/دقيقة | $29/شهر |
| Enterprise | 500 طلب/دقيقة | $99/شهر |
| مخصص | قابل للتفاوض | تواصل مع المبيعات |