رموز الأخطاء

رموز حالة HTTP في Listings API، ورموز الأخطاء SYxxxxx لكل من Listings وSocial، وأشكال استجابات الأخطاء الثلاثة التي تُرجعها واجهة API بالإصدار v4.

تستخدم Listings API رموز حالة HTTP المعتادة للإبلاغ عن نتيجة الطلب. تبدأ رموز الأخطاء بالبادئة SY وتُضمَّن في السلسلة النصية message للخطأ، بالتنسيق SYxxxxx: <human-readable reason>.

اقرأ رمز الحالة أولًا

تُرجع حالات الفشل على مستوى الطلب، وهي فشل المصادقة والتفويض وعدم العثور على المورد وتجاوز حدود المعدل والطلبات غير السليمة وأخطاء الخادم، حالة 4xx أو 5xx المطابقة مع مصفوفة errors في المستوى الأعلى. تعني الحالة 2xx أن الطلب قد قُبل. تنطبق قاعدة إضافية على عمليات الكتابة: يمكن لاستدعاء الإنشاء أو التحديث أو النشر أن يُبلّغ عن نتائج التحقق من صحة الحقول في جسم استجابته حتى مع الحالة 200، لذا تحقّق أيضًا من جسم الاستجابة لعمليات الكتابة (راجع ملاحظة التحقق من صحة عمليات الكتابة أدناه).

رموز حالة HTTP

HTTP status code summary

الحالة	المعنى	رمز `SY` المعتاد	استثناء Python SDK
`200 OK`	نجح الطلب. بالنسبة إلى عمليات الكتابة، تحقّق أيضًا من جسم الاستجابة (انظر أدناه).	-	-
`400 Bad Request`	طلب غير سليم، أو عامل تصفية يتعذر تحليله، أو قيمة enum غير صالحة، أو معرّف بتنسيق غير سليم.	`SY90006`, `SY90001`	`ValidationError`
`401 Unauthorized`	مفتاح API مفقود أو بتنسيق غير سليم أو ملغى. ليس لديك مفتاح بعد؟ احصل على تصريح ليوم واحد مجانًا لبيئة الاختبار عندما يكون متاحًا.	`SY90005`	`AuthenticationError`
`402 Payment Required`	توجد فاتورة غير مدفوعة على الحساب، لذا فإن الوصول إلى API معلّق. تؤدي الفاتورة غير المدفوعة الخاصة بخدمة Social وحدها إلى تعليق نقاط نهاية Social فقط. راجع `payment_required` و`social_payment_required`.	-	`APIError`
`403 Forbidden`	المفتاح صالح، لكنه لا يملك إذن الوصول إلى المورد.	`SY90003`	`PermissionDeniedError`
`404 Not Found`	المسار أو المورد المحدد بواسطة معرّف غير موجود.	`SY90002`	`NotFoundError`
`422 Unprocessable Entity`	كان الطلب سليم البنية، لكن تعذرت معالجة إحدى القيم (مثل فئة غير معروفة أو ملتبسة).	-	`ValidationError`
`429 Too Many Requests`	لقد تجاوزت حد المعدل المسموح به في خطتك. التزم بترويسة `Retry-After`.	-	`RateLimitError`
`5xx`	خطأ في الخادم. يمكن إعادة محاولة عملية قراءة بأمان مع زيادة مدة الانتظار بين المحاولات؛ راجع التنبيه الخاص بالكتابة أدناه قبل تكرار عملية كتابة.	`SY90007`	`InternalServerError`

ثلاثة أشكال للاستجابة

تتضمن معظم حالات الفشل مصفوفة errors، إما في المستوى الأعلى أو متداخلة داخل نتيجة العملية، كما توضح الأقسام أدناه. تُرجع بعض حالات الفشل كائن error واحدًا بدلًا من ذلك: تقييد المعدل (429) وبعض حالات الفشل على مستوى الطلب (400/500 مع code مثل INTERNAL_SERVER_ERROR). تحقّق من الحالتين: errors مصفوفة، وerror كائن.

1. على مستوى الطلب: `errors[]` في المستوى الأعلى

توقف حالات فشل المصادقة والتفويض والطلبات غير السليمة المعالجة قبل تنفيذ العملية. وتُرجع حالة 4xx المطابقة (أعلاه) مع الخطأ في المستوى الأعلى من الاستجابة.

JSON

{  "data": { "createLocation": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

2. التحقق من صحة عمليات الكتابة: `data.<operation>.errors[]` متداخل

يُرجع طلب الإنشاء أو التحديث أو النشر الحالة HTTP 200 ما دام سليم البنية. إذا خالفت المدخلات قاعدة عمل، يُبلَّغ عن الفشل بشكل متداخل ضمن الحمولة الخاصة بالعملية في data.<operation>.errors. عند النجاح، تكون هذه المصفوفة موجودة وفارغة ("errors": []).

JSON

{  "data": {    "createLocation": {      "errors": [        { "message": "SY10126: City is Mandatory" },        { "message": "SY10010: state_iso" }      ],      "location": null    }  }}

3. على مستوى البوابة: كائن `error` واحد في المستوى الأعلى

يؤدي تقييد المعدل وأعطال البوابة غير المتوقعة إلى إيقاف المعالجة قبل الترجمة وإرجاع كائن error واحد يحتوي على code وmessage وcorrelation_id. راجع rate_limited أدناه للاطلاع على جسم استجابة 429.

اقرأ data.<operation>.errors دائمًا عند إجراء عملية كتابة، حتى مع الحالة 200 وكائن data.<operation> يحتوي على بيانات: فقد تفشل عملية الكتابة جزئيًا وتُبلّغ عن ذلك هنا.

لا تحتوي استجابة 402 Payment Required على غلاف error: تكون code وmessage وdoc_url في المستوى الأعلى، وكذلك pay_url عند وجود فاتورة مستحقة الدفع. راجع payment_required أدناه.

إعادة محاولة الكتابة ليست بلا تبعات

لا تدعم واجهة API بالإصدار v4 الترويسة Idempotency-Key: إذ يجري تجاهلها، ولا تكتشف أي نقطة نهاية عمليات الكتابة المتكررة. إذا انتهت مهلة استدعاء إنشاء أو تحديث أو نشر، أو أرجع الحالة 5xx، فقد يكون الخادم قد حفظ التغيير رغم ذلك، لذا قد تؤدي إعادة المحاولة دون تحقق إلى إنشاء موقع أو منشور أو رد على تقييم مكرر.

أعد محاولة عمليات القراءة بحرية مع زيادة مدة الانتظار بين المحاولات. أما لعملية الكتابة، فاقرأ البيانات للتحقق أولًا: ابحث عن السجل باستخدام مفتاح تتحكم فيه (storeId، أو رمز متجر، أو قائمة ردود التفاعل)، ولا تكرر الاستدعاء إلا إذا كان السجل غير موجود بالفعل.

الرموز الشائعة

Common SY error codes

الرمز	الرسالة	حالة HTTP	المعنى
`SY90005`	`Invalid Token`	`401`	مفتاح API مفقود أو بتنسيق غير صحيح أو ملغى. أعد إصدار مفتاح من لوحة التحكم وأرسله بصيغة `Authorization: API <your-key>`.
`SY90001`	`Not authorized to access this resource`	`401` / `403`	رُفض المفتاح لهذا المورد. ترفع كلتا حزمتي SDK للغتي Python وNode هذا الخطأ بوصفه `AuthenticationError`.
`SY90002`	`Invalid Id`	`404` / `400`	تعذّر العثور على ما يشير إليه المعرّف في المسار أو الوسيطة (غالبًا ما يكون معرّف relay غير صحيح أو غير مرمّز بتنسيق base64).
`SY10126`	`City is Mandatory`	`200` (جسم الاستجابة)	أُغفل حقل مطلوب (`city`) من المدخلات.
`SY10010`	`state_iso`	`200` (جسم الاستجابة)	قيمة `stateIso` مفقودة أو غير صالحة. راجع نقطة نهاية البلدان والولايات للاطلاع على القيم الصالحة.

تقابل رموز التحقق من الصحة ضمن النطاق SY10xxx حقلًا محددًا من حقول المدخلات؛ ويحدد message اسم الحقل أو القاعدة التي لم تُستوفَ. أما رموز المصادقة والتخويل ضمن النطاق SY90xxx فتخص الطلب بأكمله وتَرِد في المستوى الأعلى مع الحالة المطابقة.

رموز الحسابات المتصلة

تصدر الرموز ضمن النطاق SY810xx عن نقاط نهاية الحسابات المتصلة التي تستورد إدراج نشاط تجاري على منصة نشر أو تربطه. وتَرِد متداخلة في جسم الاستجابة عند إرجاع HTTP 200 (بنية الاستجابة 2 أعلاه)، لذا اقرأ data.<operation>.errors حتى عندما تشير الحالة إلى النجاح.

SY810xx connected-account and import codes

الرمز	المعنى	الإجراء المطلوب
`SY81019`	تعذّر العثور على مستخدم للحساب المرتبط بالمفتاح.	تواصل مع الدعم: لا يوجد مستخدم أساسي نشط للحساب.
`SY81066`	لا يوجد `connectedAccountId`، أو أن الحساب مؤرشف.	أعد قراءة المعرّف من `GET /connected-accounts`.
`SY81067`	تعذّر فك ترميز `connectedAccountListingId` أو العثور على ما يشير إليه.	أعد جلبه من `id` في سجل connected-account-listings.
`SY81068`	إدراج النشاط التجاري هذا مرتبط بالفعل بموقع.	افصل ارتباطه أولًا، أو اختر إدراج نشاط تجاري آخر.
`SY81069`	لم تعد بيانات اعتماد الحساب المتصل صالحة.	أعد توصيل الحساب عبر connect-google أو connect-facebook.
`SY81070`	إدراج النشاط التجاري لا يتبع الحساب المتصل الذي حددته.	اربط كل إدراج نشاط تجاري بالحساب الذي جُلب منه. من الأسباب الشائعة جلب إدراجات الأنشطة التجارية دون تضمين `connectedAccountId` في جسم الطلب، مما يؤدي إلى إرجاع إدراجات الأنشطة التجارية التابعة لحساب آخر.
`SY81071`	حدث خطأ غير متوقع أثناء إنشاء الموقع.	أعد المحاولة؛ وإذا استمر الخطأ، فتواصل مع الدعم.
`SY81072`	فشل إنشاء الموقع أثناء البناء أو الحفظ.	أعد المحاولة؛ وإذا استمر الخطأ، فتواصل مع الدعم.
`SY81073`	نوع إدراج النشاط التجاري غير مدعوم للاستيراد.	يمكن استيراد إدراجات الأنشطة التجارية من Google وFacebook فقط.
`SY81074`	لم تُرجع Google أي بيانات لإدراج النشاط التجاري.	تأكد من أن إدراج النشاط التجاري لا يزال موجودًا وأن الحساب لا يزال يديره.
`SY81075`	تم تجاوز حد معدل طلبات API الخاص بـ Google.	أعد المحاولة لاحقًا مع زيادة مدة الانتظار تدريجيًا بين المحاولات.
`SY81076`	فشل جلب إدراج النشاط التجاري من Google.	أعد المحاولة؛ وتحقق من أذونات الحساب لدى Google.
`SY81077`	تعذّر تحديد البلد من صفحة Facebook.	أضف بلدًا إلى عنوان الصفحة على Facebook، ثم أعد المحاولة.
`SY81078`	فشل بناء بيانات الموقع من صفحة Facebook.	أعد المحاولة؛ وإذا استمر الخطأ، فتواصل مع الدعم.
`SY81081`	لم تُعيَّن فئة أساسية لإدراج النشاط التجاري.	عيّن فئة أساسية لإدراج النشاط التجاري، ثم أعد المحاولة.
`SY81082`	بلد إدراج النشاط التجاري غير مدعوم.	راجع نقطة نهاية البلدان والولايات للاطلاع على البلدان المدعومة.
`SY81083`	تعذّر استيراد إدراج النشاط التجاري من Google.	تواصل مع الدعم مع إرفاق الطابع الزمني.
`SY81084`	حدث خطأ داخلي أثناء التحضير للاستيراد من Facebook.	أعد المحاولة؛ وإذا استمر الخطأ، فتواصل مع الدعم مع إرفاق الطابع الزمني.
`SY81085`	تعذّر استيراد صفحة Facebook.	تواصل مع الدعم مع إرفاق الطابع الزمني.
`SY81086`	رُفض إنشاء الموقع بسبب قاعدة عمل. يحمل `message` المتداخل الرمز الأساسي، مثل `SY10151` عندما يستنفد الحساب عدد المواقع المسموح به.	اقرأ الرسالة المتداخلة؛ وفي حالة `SY10151`، أضف حزمة إضافية لموقع أو رقِّ الخطة.
`SY81087`	فشل طلب إنشاء الموقع.	أعد المحاولة؛ وإذا استمر الخطأ، فتواصل مع الدعم مع إرفاق الطابع الزمني.
`SY81088`	فشل إنشاء الموقع لسبب غير معروف.	تواصل مع الدعم مع إرفاق الطابع الزمني.
`SY81089`	أرجع استدعاء خدمة داخلية حالة لا تشير إلى النجاح. لا توجد مشكلة في طلبك.	أعد المحاولة مرة واحدة؛ وإذا استمر الخطأ، فتواصل مع الدعم مع إرفاق الطابع الزمني حتى نتمكن من تتبع الاستدعاء الداخلي.
`SY81090`	حدث خطأ غير متوقع أثناء الاستدعاء الداخلي لإنشاء الموقع.	أعد المحاولة؛ وإذا استمر الخطأ، فتواصل مع الدعم مع إرفاق الطابع الزمني.

تأتي الرموز ضمن النطاق SY950xx من نقاط نهاية Social: العلامات التجارية والاتصالات ومنشورات التواصل الاجتماعي. وكما هو الحال مع رموز الحسابات المتصلة، تَرِد هذه الرموز متداخلة في جسم الاستجابة عند HTTP 200، لذا اقرأ data.<operation>.error (وdata.<operation>.errors في مسارات العمليات المجمّعة) حتى عندما تشير الحالة إلى النجاح.

SY950xx Social codes

الرمز	المعنى	الإجراء المطلوب
`SY95041`	بلغ الحساب الحد الأقصى لعدد العلامات التجارية. لا يمكن أن تحدث هذه الحالة على خطة API: فعدد العلامات التجارية فيها غير محدود.	لا يلزم اتخاذ أي إجراء على خطة API. إذا ظهر لك هذا الرمز في أي وقت، فأبلغ عنه: إذ يُفترض أن تُرجع `GET /social/limits` القيمة `brands: null`.
`SY95042`	بلغ الحساب الحد الأقصى لعدد الاتصالات في فترة الفوترة الحالية.	يُقارَن الحد الأقصى بالقيمة `usage.connections` من `GET /social/limits`، وهي العدد الخاضع للفوترة: الاتصالات القائمة حاليًا مضافًا إليها الاتصالات التي حُرّرت خلال هذه الفترة. تظل الخانة التي تُفرَغ عن طريق قطع الاتصال أو أرشفة علامة تجارية محجوزة حتى نهاية الفترة، لذا فإن قطع اتصال مؤخرًا لا يزيل هذا الخطأ. أعد ربط أحد الحسابات التي حرّرتها بالعلامة التجارية التي كان مرتبطًا بها (مجانًا، إذ يُعاد استخدام الخانة نفسها)، أو اشترِ حزمة أخرى تضم 5 اتصالات (تُتاح فورًا)، أو انتظر التجديد، حين تعود خانات `usage.connectionsReleased`. ربط حساب محرّر بعلامة تجارية مختلفة لا يعيد استخدام الخانة. راجع الخطط والإضافات.
`SY95043`	لا توجد علامة تجارية بهذا المعرّف في هذا الحساب، أو أن العلامة التجارية مؤرشفة.	أعد قراءة المعرّف من `GET /social/brands`. معرّفات العلامات التجارية هي معرّفات UUID عادية، وليست معرّفات Relay بترميز Base64.
`SY95044`	هذه المنصة غير مفعّلة لهذا الحساب.	لا تشمل خطة Social الخاصة بالحساب المنصة التي طلبت الاتصال بها. تواصل مع الدعم أو اختر منصة متاحة للحساب.
`SY95045`	ليس لدى العلامة التجارية قناة متصلة على هذه المنصة.	وجّه المستخدم إلى رابط اتصال خاص بهذه المنصة، أو أزلها من `platforms`. يظهر هذا الرمز أيضًا عند قطع اتصال القناة بعد جدولة المنشور.
`SY95046`	الجدولة أو المنطقة الزمنية غير صالحة.	أرسل `scheduledAt` أو `scheduleDate` + `scheduleTime`، ولا ترسل الخيارين معًا مطلقًا. يتطلب `scheduledAt` إزاحة عن UTC؛ أما `scheduleTime` فهو `HH:MM`. المناطق الزمنية هي معرّفات IANA (`tzCode`).
`SY95047`	لا توجد مهمة مجمّعة بهذا المعرّف في هذا الحساب.	أعد قراءة `job.id` من استجابة الإنشاء المجمّع. لا يُحتفظ بالمهام إلى الأبد.
`SY95048`	يتجاوز الطلب المجمّع الحد الأقصى لعدد الصفوف.	أرسل 500 صف كحد أقصى في كل طلب، وقسّم الباقي إلى دفعات إضافية. لم يُنشأ أي شيء.
`SY95049`	عنوان URL لإعادة التوجيه غير صالح.	يجب أن تكون قيمتا `redirectUrl` و`errorUrl` في رابط اتصال عنوانَي URL مطلقين من نوع `https` تتحكم فيهما.
`SY95050`	فشل التحقق من صحة الدفعة؛ راجع الأخطاء الخاصة بكل صف.	لم يُنشأ أي شيء. اقرأ `job.results[]`: يتضمن كل صف مرفوض `index` الخاص به، الذي يبدأ ترقيمه من 0، و`clientReference` الخاص به، والسبب في `errors[]`. صحّح تلك الصفوف وأعد إرسال الدفعة بأكملها.
`SY95051`	لم تستوفِ العلامة التجارية شرط مرور 90 يومًا على إنشائها.	لا يمكن أرشفة علامة تجارية قبل مرور 90 يومًا على إنشائها. تتضمن الاستجابة أيضًا `status: "TENURE_NOT_MET"`، ولم يتغير أي شيء. أعد المحاولة بعد اليوم 90، وعندها تُؤرشف العلامة التجارية واتصالاتها فورًا، مع بقاء خانات اتصالاتها محجوزة حتى نهاية فترة الفوترة. راجع قاعدة المدة منذ الإنشاء.
`SY95052`	القناة المتصلة لا تنتمي إلى هذه العلامة التجارية.	اربط كل اتصال بالعلامة التجارية التي أُنشئ ضمنها. يشيع هذا الخطأ عند إنشاء استدعاء للإحصاءات باستخدام منشور لعلامة تجارية ومعرّف قناة لعلامة تجارية أخرى.

يشير SY95042 وSY95044 إلى عدم استيفاء استحقاقات الخطة، وليس إلى أخطاء في المدخلات: ستفشل إعادة المحاولة بالطريقة نفسها إذا لم تُغيَّر الخطة. أما SY95045 وSY95046 وSY95049 وSY95052 فهي أخطاء في المدخلات يمكن تصحيحها في الطلب التالي.

رموز استحقاقات Listings

Listings plan codes

الرمز	المعنى	الإجراء المطلوب
`SY10150`	بلغ الحساب الحد الأقصى لعدد المواقع.	أرشف موقعًا، أو اشترِ إضافة لموقع إضافي، أو رقِّ الخطة. راجع الخطط والإضافات.
`SY10151`	استنفد الحساب السعة المخصصة للمواقع في هذه الخطة. عند استخدام تصريح ليوم واحد لبيئة الاختبار، يكون كلا الموقعين المتاحين بموجبه قيد الاستخدام.	تنطبق الحلول نفسها المذكورة في `SY10150`. عند استخدام تصريح ليوم واحد، حدِّث موقعًا موجودًا أو اختر خطة مدفوعة. يظهر أيضًا متداخلًا داخل `SY81086` عند إنشاء موقع من إدراج نشاط تجاري تابع لحساب متصل.
`SY10152`	لم يبقَ الموقع نشطًا مدة كافية للسماح بأرشفته.	يجب أن تبقى المواقع نشطة طوال الحد الأدنى للمدة المحدد للحساب، وهو 90 يومًا افتراضيًا، قبل أن يقبلها `POST /locations/archive`. انتظر حتى انقضاء هذه المدة.
`SY10155`	ليس لدى الحساب خطة Listings، لذا لا يمكن إنشاء مواقع.	ينتمي مفتاح API إلى حساب ليس لديه اشتراك Listings، مثل حساب لديه اشتراك Social فقط. المواقع جزء من منتج Listings؛ اشترك فيه قبل استدعاء `POST /locations`.

`rate_limited`

429 Too Many Requests: تجاوز الحساب حد معدل الطلبات المسموح به في خطته. جسم الاستجابة هو استجابة الخطأ القياسية، ويحمل تلميحًا في retry_after_seconds، وقيمة correlation_id لتضمينها في طلبات الدعم، وقيمة doc_url تربط بهذا القسم:

JSON

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

انتظر المدة المحددة في retry_after_seconds (أو في ترويسة Retry-After إن وُجدت)، ثم أعد المحاولة مع زيادة مدة الانتظار أُسّيًا بين المحاولات. راجع حدود معدل الطلبات للاطلاع على الحدود الخاصة بكل خطة وتنفيذ مرجعي لآلية زيادة مدة الانتظار بين المحاولات.

`payment_required`

402: لم تنجح الدفعة الأخيرة لهذا الحساب، لذا أُوقفت جميع نقاط نهاية /api/v4 مؤقتًا. يتضمن جسم الاستجابة pay_url، وهي صفحة Stripe الخاصة بالفاتورة غير المدفوعة، عند توفرها، وتحمل ترويسة الاستجابة X-Error-Code قيمة code نفسها. لا يزال بإمكانك فتح صفحة الفوترة في لوحة التحكم للدفع.

JSON

{  "code": "payment_required",  "message": "This account has an unpaid invoice, so API access is paused. Pay the invoice to restore access.",  "pay_url": "https://invoice.stripe.com/i/acct_123/test_abc",  "doc_url": "https://listingsapi.com/docs/error-codes#payment_required"}

تُستعاد إمكانية الوصول خلال دقيقة من سداد آخر فاتورة مفتوحة. إذا ظلت الفاتورة غير مدفوعة بعد 3 أيام من أول محاولة دفع فاشلة، يُلغى اشتراك Listings وتُؤرشف مواقع الحساب. إذا كان لدى الحساب أيضًا اشتراك Social نشط، فإنه يحتفظ بإمكانية الوصول إلى Social؛ وإلا يُغلق الحساب وتتوقف مفاتيح API الخاصة به عن العمل.

`social_payment_required`

402: لم تنجح الدفعة الأخيرة لاشتراك Social، لذا أُوقفت نقاط نهاية Social (/api/v4/social/*) مؤقتًا. تستمر نقاط نهاية Listings في العمل. يحتوي جسم الاستجابة على الحقول نفسها الموجودة في payment_required، مع "code": "social_payment_required". إذا ظلت الفاتورة غير مدفوعة بعد 3 أيام من أول محاولة دفع فاشلة، يُلغى اشتراك Social وتُؤرشف العلامات التجارية الخاصة بالحساب. يُغلق الحساب الذي ليس لديه اشتراك Listings، وتتوقف مفاتيح API الخاصة به عن العمل.

أخطاء مستوى التحكم في بوابة المطورين

تُرجع نقاط نهاية إدارة الحساب والمفاتيح في بوابة المطورين (مسارات API الخاصة بلوحة التحكم نفسها) استجابة خطأ واحدة ذات بنية محددة، تختلف عن صيغ errors[] الخاصة بـ REST أعلاه. يحمل كل code قيمة correlation_id وقيمة doc_url تربط بالقسم المقابل هنا.

JSON

{  "error": {    "code": "AUTH_INVALID_KEY",    "message": "Session is invalid or expired.",    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#auth_invalid_key"  }}

`auth_missing_key`

401: لم تُقدَّم بيانات اعتماد. سجِّل الدخول مجددًا، أو أرسل مفتاحك بصيغة Authorization: API <your-key>.

`auth_invalid_key`

401: الجلسة أو المفتاح غير صالح أو منتهي الصلاحية. أعِد المصادقة أو أعِد إصدار مفتاح من لوحة التحكم.

`auth_insufficient_scope`

403: بيانات الاعتماد صالحة لكنها لا تمنح الإذن بتنفيذ هذا الإجراء. لا يمكن لمفتاح ذي نطاق صلاحيات للقراءة استدعاء نقاط نهاية الكتابة؛ أصدِر مفتاحًا للكتابة إذا كنت بحاجة إليه.

`not_found`

404: المورد المطلوب، أو مورد يُشار إليه بواسطة ID، غير موجود.

`conflict`

409: يتعارض الطلب مع الحالة الحالية للمورد (مثل إبطال مفتاح أُبطل بالفعل).

`validation_failed`

422: لم يجتز جسم الطلب التحقق من الصحة. يحدد الحقلان field وdetails في الاستجابة المُدخل الذي تسبب في فشل التحقق.

`internal_error`

500: خطأ غير متوقع من جانب الخادم. أعِد محاولة القراءة مع زيادة مدة الانتظار أُسّيًا بين المحاولات؛ أما في حالة الكتابة، فاقرأ السجل مجددًا أولًا (راجع إعادة محاولة الكتابة ليست بلا تبعات). أدرج قيمة correlation_id إذا تواصلت مع الدعم.

`dependency_unavailable`

503: إحدى الخدمات التي تعتمد عليها API غير متاحة مؤقتًا. أعِد المحاولة مع زيادة مدة الانتظار بين المحاولات.

للاطلاع على معلومات حول 429، راجع rate_limited أعلاه.

معالجة الأخطاء في الشيفرة

تحقّق من حالة HTTP أولًا؛ ثم، في عمليات الكتابة، افحص جسم الاستجابة بحثًا عن مصفوفة errors متداخلة:

Python

from listingsapi import APIError, ListingsAPI client = ListingsAPI(api_key=os.environ["LISTINGSAPI_KEY"]) try:    location = client.locations.create(input=payload)except APIError as e:    # Raised for a non-2xx status (AuthenticationError, ValidationError, and    # so on) and for an error payload returned inside a 200 body.    raise RuntimeError(f"Listings API error: {e}") from e

عند استخدام واجهة HTTP API مباشرةً، يُجرى الفحصان نفساهما صراحةً: رمز الحالة أولًا ثم حمولة الاستجابة:

Python

resp = requests.post(    "https://listingsapi.com/api/v4/locations",    headers={"Authorization": f"API {os.environ['LISTINGSAPI_KEY']}"},    json=payload,    timeout=30,)resp.raise_for_status()body = resp.json() op = (body.get("data") or {}).get("createLocation") or {}if op.get("errors"):    messages = [e["message"] for e in op["errors"]]    raise RuntimeError(f"Listings API error: {messages}")

تتولى حزمة Python SDK كلا الفحصين نيابةً عنك: فهي تربط كل حالة HTTP باستثناء ذي نوع محدد، وترفع استثناءً أيضًا عند إرجاع حمولات خطأ داخل جسم استجابة 200.