الأخطاء

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

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

صيغة الخطأ

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

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

string

مطلوب

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

string

مطلوب

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

string

مطلوب

رابط إلى وصف رمز الخطأ في توثيق 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 طلباته في النافذة الحالية. راجع حدود الطلبات.
`internal_server_error`	500	حدث خطأ من جانبنا. أعد المحاولة لاحقًا، وتواصل مع الدعم إذا استمر ذلك.

أخطاء التحقق

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

{
  "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. راجع حدود الطلبات.
أعد محاولة أخطاء 5xx مع تراجع أُسّي.

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

كل طلب يُرجع 404 "This endpoint is not available."

الواجهة في مرحلة تجريبية ولم تُفعَّل لمساحة عملك بعد.

404 "This endpoint does not exist."

المسار خاطئ. قارنه بصفحات نقاط النهاية، وتحقّق من أنه يبدأ بـ /api/v1/.

403 "Access denied: This account does not have an active subscription."

انتهى اشتراك مالك مساحة العمل. يعمل مفتاح API مجددًا بمجرد أن يجدّد المالك اشتراكه.

403 "API access is not available for this role."

دورك في مساحة العمل هو Viewer. لا يستطيع استخدام الواجهة إلا مالك مساحة العمل ومستخدمو Editor.

API

صيغة الخطأ

رموز الأخطاء

أخطاء التحقق

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

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

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

حدود الطلبات

المصادقة

​صيغة الخطأ

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

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

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

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

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

حدود الطلبات

المصادقة

صيغة الخطأ

رموز الأخطاء

أخطاء التحقق

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

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

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