> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# حدود الطلبات

> عدد الطلبات التي يمكنك إرسالها وكيفية التعامل مع استجابات 429.

> [!NOTE]
>
> GetQR API في مرحلة تجريبية (beta) ومتاحة لمساحات عمل مختارة. قد تتغير التفاصيل قبل الإصدار العام.

تحدّ GetQR API من عدد الطلبات التي يمكن لكل مفتاح API إرسالها، حتى لا يتسبب تكامل واحد في إبطاء الواجهة على الجميع.

## الحدود

| الحد | القيمة |
| - | - |
| الطلبات لكل مفتاح API | 600 في الدقيقة |

يُحتسب الحد على نافذة منزلقة مدتها دقيقة واحدة، ويُطبَّق على جميع نقاط النهاية معًا. لا يحتاج [فحص الحالة](https://docs.getqr.com/ar/api/endpoints/health.md) إلى مفتاح ولا يُحتسب.

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

تحمل الاستجابات للطلبات التي تستخدم مفتاح API صالحًا هذه الترويسات، بما في ذلك استجابات الأخطاء:

| الترويسة | الوصف |
| - | - |
| `X-RateLimit-Limit` | الحد الأقصى لعدد الطلبات في كل نافذة. |
| `X-RateLimit-Remaining` | الطلبات المتبقية في النافذة الحالية. |
| `X-RateLimit-Reset` | وقت إعادة تعيين النافذة، كطابع زمني Unix بالمللي ثانية. |
| `Retry-After` | عدد الثواني حتى إعادة تعيين النافذة، مقرّبًا للأعلى. انتظر هذه المدة قبل إعادة المحاولة. |

## عند تجاوز الحد

عند تجاوز الحد، تُرجع الواجهة `429` مع الرمز `rate_limit_exceeded` والترويسات نفسها:

```http theme={null}
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1792764060000
Retry-After: 37

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests.",
    "doc_url": "https://getqr.com/account/api-docs#error-rate_limit_exceeded"
  }
}
```

انتظر حتى وقت إعادة التعيين قبل إرسال مزيد من الطلبات. أضف تأخيرًا عشوائيًا (jitter) حتى لا تعيد عدة عمليات المحاولة في اللحظة نفسها، واستخدم التراجع الأُسّي مع أخطاء `5xx`:

```javascript theme={null}
async function getqrFetch(url, options = {}, maxRetries = 5) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, {
      ...options,
      headers: {
        Authorization: `Bearer ${process.env.GETQR_API_KEY}`,
        ...options.headers,
      },
    });

    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt >= maxRetries) return res;

    // On 429, wait for Retry-After (seconds). Otherwise back off: 1s, 2s, 4s…
    const retryAfter = Number(res.headers.get("Retry-After"));
    const wait =
      res.status === 429 && retryAfter > 0
        ? retryAfter * 1000
        : 1000 * 2 ** attempt;
    const jitter = Math.random() * 250;

    await new Promise((r) => setTimeout(r, wait + jitter));
  }
}
```

> [!TIP]
>
> لا تُعد محاولة `POST /api/v1/qrs` إلا مع الترويسة `Idempotency-Key`. عندها لن تُنشئ إعادة المحاولة رمز QR ثانيًا أبدًا. راجع [عدم التكرار (Idempotency)](https://docs.getqr.com/ar/api/introduction.md#عدم-التكرار-idempotency).

## البقاء ضمن الحد

* راقب `X-RateLimit-Remaining` وأبطئ قبل أن تصل إلى 0.
* استخدم [الإنشاء المجمّع لرموز QR](https://docs.getqr.com/ar/api/endpoints/bulk-qr-creations.md) بدلًا من طلب واحد لكل رمز QR.
* اجلب حتى 100 نتيجة في الصفحة باستخدام `pageSize=100`. راجع [ترقيم الصفحات](https://docs.getqr.com/ar/api/introduction.md#ترقيم-الصفحات).
* خزّن صور QR مؤقتًا: تُرجع عمليات التنزيل `ETag`، فيمكنك إرسال `If-None-Match` والحصول على `304 Not Modified` عندما لا يتغير شيء.

## الخطوات التالية

> [card] [الأخطاء](https://docs.getqr.com/ar/api/errors.md)

> [card] [رموز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.