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

> حدود معدّل الطلبات لكل مفتاح API، وترويسات الاستجابة الخاصة بحدود المعدّل، وretry-after عند 429 و503، والترويسات الأخرى التي ترسلها Fileverity API.

المصدر: https://fileverity.com/ar/docs/rate-limits

يمكن لكل مفتاح API إرسال 120 طلبًا في الدقيقة. يُحتسب الحد ضمن نوافذ مدة كل منها دقيقة واحدة، ويشمل جميع نقاط النهاية، بما فيها الطلبات التي تعيد خطأً. وعندما تُستنفد النافذة، تُرفض الطلبات التالية بالحالة `429` وبرمز الخطأ `rate_limited` إلى أن تبدأ نافذة جديدة.

هل تحتاج إلى حدود أعلى أو أسعار للكميات الكبيرة؟ [تواصل مع فريق المبيعات](https://fileverity.com/ar/contact).

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

تحمل كل استجابة لطلب مصادَق عليه حالة نافذتك:

| الترويسة | المعنى |
| --- | --- |
| `x-ratelimit-limit-requests` | عدد الطلبات المسموح بها في كل نافذة. |
| `x-ratelimit-remaining-requests` | عدد الطلبات المتبقية في النافذة الحالية. |
| `x-ratelimit-reset-requests` | عدد الثواني المتبقية حتى تبدأ نافذة جديدة. |
| `retry-after` | لا تظهر إلا مع `429` برمز الخطأ `rate_limited` ومع `503` برمز الخطأ `service_unavailable`. عدد الثواني التي ينبغي انتظارها قبل الطلب التالي. ولا يحملها `pending_files_limit` (وهو أيضًا `429`). |

لا تحمل هذه الترويسات الطلبات المرفوضة بسبب مفتاح مفقود أو غير صالح (`401`).

**التزم بالترويسة retry-after: JavaScript**

```javascript
async function call(url, init) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const response = await fetch(url, init);
    if (response.status !== 429) return response;
    const wait = Number(response.headers.get("retry-after")) || 1;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  throw new Error("Rate limited");
}
```

**التزم بالترويسة retry-after: Python**

```python
import time

def call(method, url, **kwargs):
    for attempt in range(5):
        response = requests.request(method, url, **kwargs)
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("retry-after", 1)))
    raise RuntimeError("Rate limited")
```

وزّع ذروات الطلبات على الزمن، وفضّل [Webhooks](https://fileverity.com/ar/docs/webhooks.md) على حلقات الاستعلام المتكرر الكثيفة، واستخدم `Prefer: wait` في [التحليلات](https://fileverity.com/ar/docs/analyses.md) بدلًا من الاستعلام المتكرر. وعندما تكون السعة المتاحة مستخدمة بالكامل، يعيد `POST /analyses` الاستجابة `503 service_unavailable` مع `retry-after`؛ راجع [عندما تكون السعة المتاحة مستخدمة بالكامل](https://fileverity.com/ar/docs/analyses.md#busy).

## ترويسات الاستجابة الأخرى

| الترويسة | أين تظهر | المعنى |
| --- | --- | --- |
| `x-request-id` | كل استجابة | معرّف الطلب، وهو موجود أيضًا في محتوى استجابات الأخطاء. |
| `cache-control: no-store` | كل استجابة | لا تُخزَّن استجابات API مؤقتًا أبدًا. |
| `preference-applied` | `POST /analyses` | `wait=N` عند الأخذ بترويسة `Prefer` التي أرسلتها. |
| `idempotent-replayed` | نقاط نهاية POST | `true` عندما تكون الاستجابة نسخة محفوظة معاد إرسالها. راجع [Idempotency](https://fileverity.com/ar/docs/idempotency.md). |
| `x-evidence-included` | `GET /analyses/{id}/report.pdf` | `false` عندما تكون أدلة المستند قد انتهت صلاحيتها ولا يتضمنها ملف PDF. |

## الترويسات التي ترسلها

- `Authorization: Bearer <key>`: مطلوبة. راجع [المصادقة والمفاتيح](https://fileverity.com/ar/docs/authentication.md).
- `Content-Type: application/json` لطلبات JSON؛ و`multipart/form-data` لعمليات الرفع عبر `POST /files`.
- `Idempotency-Key`: اختيارية، في طلبات POST.
- `Prefer: wait=N`: اختيارية، في `POST /analyses`.

مثال: يعرض `curl -i https://api.fileverity.com/v1/models -H "Authorization: Bearer $FILEVERITY_API_KEY"` جميع ترويسات الاستجابة.