# لا نتائج أو خطأ في API: كيف نفرق؟

> تمييز النتيجة الفارغة، الرد الجزئي، وخطأ واجهة برمجة تطبيقات ROOTE. تحقق من الإحداثيات، الفلاتر، التغطية، والقيود لعرض الرسالة الصحيحة.

Source: https://www.roote.ai/ar/guides/%D9%84%D8%A7-%D9%86%D8%AA%D8%A7%D8%A6%D8%AC-%D8%A7%D9%88-%D8%AE%D8%B7%D8%A3-%D9%81%D9%8A-%D9%88%D8%A7%D8%AC%D9%87%D8%A9-%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D8%A7%D9%84%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-%D9%83%D9%8A%D9%81-%D9%86%D9%81%D8%B1%D9%82/
Language: ar
Author: ROOTE

تتطلب واجهة برمجة تطبيقات بدون نتيجة وأخرى بها خطأ معالجات مختلفة. قد تنجح عملية البحث دون إرجاع أي موقع داخل النطاق المطلوب. أما خطأ الشبكة أو الوصول إلى حد أقصى أو عدم توفر المصدر، فإنه يمنع استخلاص استنتاج من البحث.

بالنسبة لROOTE، تحقق أولًا من رد HTTP ثم حالة العمل، المجموعة المتوقعة والتغطية. هذا يمنع عرض "لا مرافق" عند فشل استدعاء الخدمات أو "لا توقفات" بعد تجاوز مهلة الانتظار.

## قراءة المستويات الثلاثة للرد

| المستوى | ما يجب التحقق منه | الاستنتاج الممكن |
| --- | --- | --- |
| النقل | الاتصال، المهلة وحالة HTTP | هل نجحت الطلب؟ |
| العقد | JSON صالح، النسخة والحقول المتوقعة | هل الرد قابل للاستخدام؟ |
| نتيجة العمل | الحالة، المجموعات، التغطية، التحذيرات والبيانات الوصفية | ماذا نعرف ضمن النطاق المطلوب؟ |

كود HTTP 200 لا يكفي للتحقق من البحث. قد يشير الرد إلى تنفيذ جزئي أو حالة خطأ. وعلى العكس، ظهور 404 في مسار ليس وسيلة عادية للتعبير عن مجموعة فارغة: تحقق من URL والعقد.

## فهم success، empty، partial و error

| الحالة | المعالجة الموصى بها |
| --- | --- |
| نجاح | اعرض الكيانات بعد التحقق واحتفظ بالقيود |
| فارغ | أبلغ بعدم وجود نتائج لهذا البحث |
| جزئي | اعرض المعلومات القابلة للاستخدام مع تحذيراتها |
| خطأ | اعرض البحث كغير متوفر؛ لا تستنتج غياب المواقع |

غياب النتيجة يتعلق بطلب ومصادر معروفة. لا يثبت غياب الخدمة فعليًا. التغطية غير الكاملة، فلتر مقيد أو حد مفروض قد يقلل النتائج.

## شجرة قرار لواجهة المستخدم الخاصة بك

```
1. La requête a-t-elle abouti ?
   Non → indisponibilité réseau ou délai dépassé.
2. Le statut HTTP est-il acceptable selon le contrat ?
   Non → traiter le code et le message d'erreur.
3. Le JSON respecte-t-il le schéma attendu ?
   Non → réponse inexploitable, jamais "aucun résultat".
4. Le statut métier est-il error ?
   Oui → recherche indisponible.
5. Le statut est-il partial ou la couverture limitée ?
   Oui → résultats utilisables + avertissement.
6. La collection attendue est-elle vide ?
   Oui → aucun résultat retourné dans ce périmètre.
   Non → afficher les résultats et leurs limites.
```

## تحقق من المعاملات بالترتيب الصحيح

تحقق أولًا من خط العرض والطول، ترتيبهما والمدينة المستخرجة. ثم تحقق من وحدة نصف القطر ومصطلحات الفلاتر. API الخدمات تستخدم types=toilets؛ وURL الخرائط يستخدم modes=toilets. هذه المعاملات تنتمي لعقود مختلفة.

قم بتوسيع بعد واحد في كل مرة: زد نصف القطر ضمن حدود الطريق أو أزل فلتر لاختبار واضح. احتفظ بسجل الطلب الأصلي. إذا وسعت تلقائيًا، أخبر المستخدم بالنطاق الجديد.

[بناء بحث API حول إحداثيات GPS](https://www.roote.ai/ar/guides/kayfa-tabhat-an-nuqata-al-munqilat-al-muqarraba-bi-api/)

## معالجة مصدر غير متوفر دون خسارة الآخرين

قد يحتوي الرد الجزئي على مواقع من مصادر استجابت بينما فشل مصدر آخر. احتفظ بهذه النتائج، انتساباتها والتحذير المناسب. لا تعرض القائمة كأنها شاملة ولا تستبدل الحقول المفقودة بقيم افتراضية مضللة.

قد تكون المعلومات القديمة المخزنة في الكاش مفيدة أيضًا إذا سمحت سياستك بهذا الحل البديل. يجب تحديدها كبالية. وقت استلام طلبك لا يُحدث عمر الملاحظة الأصلية.

## تكييف الرسائل وإجراءات الاسترجاع

| الحالة | رسالة لتكييفها مع واجهتك | الإجراء |
| --- | --- | --- |
| فارغ | لا نتائج في هذه المنطقة مع هذه الفلاتر | غيّر المنطقة أو الفلاتر |
| جزئي | بعض النتائج متاحة؛ البحث غير كامل | اعرض النتائج والإنذار |
| خطأ في التحقق | البحث يحتوي على معامل غير صالح | صحح الطلب |
| التوثيق أو الحقوق | هذا الوصول لا يسمح بهذا البحث | تحقق من الحساب أو الرموز |
| حد أو عدم توفر | البحث غير متوفر مؤقتًا | احترم تعليمات الاسترجاع |

لرمز 429، راجع تعليمات الخدمة وربما Retry-After. الخطأ 400 يتطلب تصحيح المعاملات؛ تكرار الطلب لا يحل المشكلة. لا تحول 401 إلى استدعاء مجهول تلقائيًا إذا قدم المستخدم رمزًا.

[مرجع أخطاء API ROOTE](https://doc.roote.ai/roote-api/errors)

[حالة خدمات ROOTE](https://status.roote.ai/)

## اختبر الحالات الأربع قبل النشر

حضّر ردود اختبار كاملة، فارغة، جزئية، مع خطأ، JSON غير صالح وتأخر مهلة. تحقق من الرسالة المعروضة، النتائج المحفوظة وعدد محاولات الاسترجاع. الاختبار الأساسي هو ألا تسبب عطل أي تأكيد على غياب الخدمات.

[تطبيق هذه القواعد على مساعد ذكاء اصطناعي](https://www.roote.ai/ar/guides/%D9%83%D9%8A%D9%81%D9%8A%D8%A9-%D8%A5%D9%86%D8%B4%D8%A7%D8%A1-%D9%85%D8%B3%D8%A7%D8%B9%D8%AF-%D9%8A%D8%AC%D8%AF-%D9%88%D8%B3%D8%A7%D8%A6%D9%84-%D8%A7%D9%84%D9%86%D9%82%D9%84-%D8%AD%D9%88%D9%84-%D8%A7%D9%84%D8%B9%D9%86%D9%88%D8%A7%D9%86/)

[فهم صيغ بيانات التنقل](https://www.roote.ai/ar/guides/gtfs-gtfs-rt-wlgbfs-matha-farq/)

## الأسئلة الشائعة

### هل تثبت قائمة فارغة غياب المراحيض؟

لا. تشير فقط إلى عدم وجود نتائج لهذا البحث والمصادر التي تم فحصها.

### هل يمكن عرض رد جزئي؟

نعم، إذا كانت الكيانات المستخدمة صالحة واحتفظت بالتحذيرات والقيود اللازمة.

### هل يجب إعادة محاولة كل خطأ؟

لا. صحح أخطاء المعاملات أو الوصول؛ قيد محاولات الاسترجاع للحوادث المؤقتة واحترم تعليمات الخدمة.