> ## 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.

# الأخطاء

> صيغة الأخطاء ورموزها التي تُرجعها GetQR API.

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

تستخدم GetQR API رموز حالة HTTP القياسية. تُرجع الطلبات الناجحة `2xx`. وتُرجع الطلبات الفاشلة `4xx` أو `5xx` مع جسم JSON يشرح ما حدث من خطأ.

## صيغة الخطأ

لكل خطأ البنية نفسها: رمز ثابت، ورسالة مقروءة، ورابط إلى وصف ذلك الرمز.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}
```

**error.code** `string` *required*

رمز خطأ ثابت قابل للقراءة آليًا. استخدمه في شيفرتك بدلًا من الرسالة. راجع [رموز الأخطاء](#رموز-الأخطاء).

**error.message** `string` *required*

وصف مقروء للمشكلة. قد تتغير صياغته.

**error.doc\_url** `string` *required*

رابط إلى وصف رمز الخطأ في توثيق API داخل حسابك على GetQR.

## رموز الأخطاء

| الرمز | حالة HTTP | متى يحدث |
| - | - | - |
| `bad_request` | 400 | الطلب مشوّه: الجسم ليس JSON صالحًا، أو الترويسة `Authorization` تفتقد البادئة `Bearer `، أو الإجراء غير مسموح في الحالة الحالية للمورد (مثل إلغاء إنشاء مجمّع منتهٍ). |
| `unauthorized` | 401 | مفتاح API مفقود أو غير صالح، على سبيل المثال لأنه أُعيد إنشاؤه. |
| `forbidden` | 403 | اشتراك مالك مساحة العمل غير نشط، أو دورك في مساحة العمل لا يسمح بهذا الإجراء. |
| `exceeded_limit` | 403 | بلغت حدًا من حدود الخطة. في خطة Single QR: إنشاء رمز QR أو تكراره بينما تحتوي مساحة العمل على رمز بالفعل، أو بدء إنشاء مجمّع. |
| `not_found` | 404 | المورد غير موجود أو ليس في مساحة عملك، أو نقطة النهاية غير موجودة، أو الواجهة غير مفعّلة لمساحة عملك. |
| `method_not_allowed` | 405 | نقطة النهاية موجودة لكنها لا تقبل طريقة HTTP هذه. تسرد الترويسة `Allow` الطرق التي تقبلها. |
| `conflict` | 409 | يتعارض الطلب مع بيانات موجودة: المعرّف النصي (slug) للرابط القصير مستخدم، أو طلب بالقيمة نفسها لـ `Idempotency-Key` لا يزال قيد التنفيذ، أو جدول زمني يتداخل مع جدول موجود، أو أرشيف مجمّع لم يجهز بعد. |
| `invite_pending` | 409 | دُعيت إلى مساحة العمل لكنك لم تنضم بعد. لا تُرجعه الطلبات بمفتاح API: مساحة عمل المفتاح هي دائمًا مساحة تنتمي إليها. |
| `invite_expired` | 410 | انتهت صلاحية دعوتك إلى مساحة العمل. لا تُرجعه الطلبات بمفتاح API للسبب نفسه. |
| `unprocessable_entity` | 422 | فشل الجسم أو معاملات الاستعلام في التحقق. تذكر الرسالة اسم الحقل وما المشكلة فيه. راجع [أخطاء التحقق](#أخطاء-التحقق). |
| `rate_limit_exceeded` | 429 | استنفد مفتاح API طلباته في النافذة الحالية. راجع [حدود الطلبات](https://docs.getqr.com/ar/api/rate-limits.md). |
| `internal_server_error` | 500 | حدث خطأ من جانبنا. أعد المحاولة لاحقًا، وتواصل مع الدعم إذا استمر ذلك. |

## أخطاء التحقق

عندما يفشل الجسم أو معاملات الاستعلام في التحقق، تُرجع الواجهة `422`. تصف الرسالة أول حقل غير صالح بالصيغة `<issue>: <field>: <details>`:

```json theme={null}
{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}
```

تستخدم الحقول المتداخلة الترميز النقطي، مثل `link.url`.

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

* اعتمد في التفرّع على `error.code`، لا على `error.message`.
* لا تُعد محاولة أخطاء `4xx` دون تغيير: أصلح الطلب أولًا. الاستثناءات هي `409` لطلب لا يزال قيد التنفيذ، و`429`.
* عند `429`، انتظر عدد الثواني الوارد في الترويسة `Retry-After`. راجع [حدود الطلبات](https://docs.getqr.com/ar/api/rate-limits.md#عند-تجاوز-الحد).
* أعد محاولة أخطاء `5xx` مع تراجع أُسّي.

## المشكلات الشائعة

> [accordion] كل طلب يُرجع 404 "This endpoint is not available."
>
> الواجهة في مرحلة تجريبية ولم تُفعَّل لمساحة عملك بعد.

> [accordion] 404 "This endpoint does not exist."
>
> المسار خاطئ. قارنه بصفحات نقاط النهاية، وتحقّق من أنه يبدأ بـ `/api/v1/`.

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> انتهى اشتراك مالك مساحة العمل. يعمل مفتاح API مجددًا بمجرد أن يجدّد المالك اشتراكه.

> [accordion] 403 "API access is not available for this role."
>
> دورك في مساحة العمل هو Viewer. لا يستطيع استخدام الواجهة إلا مالك مساحة العمل ومستخدمو Editor.

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

> [card] [حدود الطلبات](https://docs.getqr.com/ar/api/rate-limits.md)

> [card] [المصادقة](https://docs.getqr.com/ar/api/authentication.md)


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