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

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

> رموز حالة HTTP، وصيغة ردود الأخطاء، وحدود المعدل لكل نقطة وصول، وإرشادات التعامل مع الأخطاء في جميع واجهات تتبع التحويلات من Scanova.

## رموز حالة HTTP

| الرمز                 | المعنى                                                       | الإجراء                                                 |
| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
| `200`                 | قُبل الحدث                                                   | لا شيء مطلوب                                            |
| `400`                 | طلب غير صالح — حقل ناقص أو صيغة خاطئة أو `site_id` غير نشطة  | صحّح محتوى الطلب                                        |
| `401`                 | الترويسة `X-API-Key` مفقودة                                  | أضف الترويسة `X-API-Key`                                |
| `403`                 | مفتاح غير صالح أو مُبطل، أو عدم تطابق بين `site_id` والمفتاح | راجع مفتاح API و`site_id`                               |
| `413`                 | الحمولة أكبر من اللازم                                       | قلّل حجمها أو قسّمها دفعات أصغر                         |
| `422`                 | خطأ في التحقق — التفاصيل في محتوى الرد                       | صحّح خطأ الحقل المحدد                                   |
| `429`                 | تجاوز حد المعدل                                              | تمهّل ثم أعد المحاولة بعد المدة في ترويسة `Retry-After` |
| `500` / `502` / `503` | خطأ في الخادم                                                | أعد المحاولة بمهلة تتضاعف تدريجيًا                      |

## صيغة رد الخطأ

تعيد جميع ردود الأخطاء محتوى JSON يتضمن التفاصيل:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "scan_session_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

وفي أخطاء `400` ذات الرسالة الواحدة:

```json theme={null}
{
  "detail": "site_id not found or inactive"
}
```

## حدود المعدل

| نقطة الوصول                 | الحد                | النطاق        |
| --------------------------- | ------------------- | ------------- |
| `POST /ct` (أحداث المتصفح)  | 100 طلب في الدقيقة  | لكل عنوان IP  |
| `POST /collect/batch`       | 100 طلب في الدقيقة  | لكل عنوان IP  |
| `POST /server-events`       | 1000 طلب في الدقيقة | لكل مفتاح API |
| `POST /server-events/batch` | 1000 طلب في الدقيقة | لكل مفتاح API |

<Note>
  تُستوعب الزيادات القصيرة فوق الحد ضمن هامش تسامح صغير. فصمّم عملاءك ليتمهلوا عند الرد `429` بدل الاتكال على ذلك الهامش.
</Note>

## نمط التعامل مع الأخطاء

### لأحداث الخادم

```javascript theme={null}
async function sendEvent(payload) {
  const response = await fetch('https://track.scanova.io/server-events', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.SCANOVA_API_KEY,
    },
    body: JSON.stringify(payload),
  });

  if (response.ok) return await response.json();

  const error = await response.json().catch(() => null);

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') ?? '60', 10);
    throw new RetryableError(`Rate limited — retry after ${retryAfter}s`, retryAfter);
  }

  if (response.status >= 500) {
    throw new RetryableError(`Server error ${response.status}`);
  }

  // 400, 401, 403, 422 — do not retry, fix the request
  throw new PermanentError(`Request failed ${response.status}: ${JSON.stringify(error)}`);
}
```

### منطق إعادة المحاولة

أعد المحاولة مع الأخطاء العابرة فقط. أما الأخطاء الدائمة فتوقف عندها فورًا.

| إعادة المحاولة؟                  | رموز الحالة                                           |
| -------------------------------- | ----------------------------------------------------- |
| نعم — أعد المحاولة بمهلة متزايدة | `429` و`500` و`502` و`503` و`504` وانتهاء مهلة الشبكة |
| لا — صحّح الطلب                  | `400` و`401` و`403` و`413` و`422`                     |

راجع [تكرار الطلبات والإرسال مرة أخرى](/ar/conversion-tracking/server/idempotency-retries) للاطلاع على تنفيذ كامل لإعادة المحاولة بمهلة تتضاعف تدريجيًا.

## الأسباب الشائعة للرد `422`

| الخطأ                                 | الحل                                                                       |
| ------------------------------------- | -------------------------------------------------------------------------- |
| صيغة `scan_session_id` غير صحيحة      | يجب أن تكون معرّف UUID صحيحًا (مثل `7ad26d4f-3181-4ef8-b6ca-b8f59499dd43`) |
| `event_name` مفقود                    | مطلوب في أحداث الخادم                                                      |
| `conversion_value.currency` غير صالحة | يجب أن تكون رمزًا من ثلاثة أحرف وفق ISO 4217 (مثل `USD` أو `EUR` أو `GBP`) |
| `properties` أكبر من اللازم           | أبقِه دون 10 كيلوبايت                                                      |
| بريد صريح في `properties`             | استخدم بدلًا منه `user_identifiers.email_hash` ببصمة SHA-256               |