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

# أخطاء واجهة API وحدود الاستخدام

> كيف تصل حالات الفشل في OTO API، وكيف تعيد المحاولة بأمان، وكيف تتعامل مع انتهاء صلاحية الرمز، وما حدود الاستخدام، وما معنى كل حالة ورمز خطأ.

لا تُقيَّم عمليات الربط بما تفعله عندما يسير كل شيء على ما يرام، بل بما تفعله عندما تتعطل شركة شحن، أو تنتهي صلاحية رمز، أو يتعذّر تحويل عنوان إلى إحداثيات.

## كيف تصل حالات الفشل؟

هناك ثلاثة أشكال مختلفة للفشل، وكل منها يحتاج إلى استجابة مختلفة.

| الشكل | كيف يبدو؟ | ما الذي تفعله؟ |
| - | - | - |
| **طلبك غير صحيح** | استجابة 4xx مع رسالة تحدد الحقل. | صحّح الطلب وأعد إرساله. إعادة المحاولة دون تغيير ستفشل بالطريقة نفسها. |
| **انتهت صلاحية الرمز** | استجابة 401. | احصل على رمز وصول جديد وأعد المحاولة مرة واحدة. ابنِ ذلك منذ البداية، فهو سيحدث كل ساعة. |
| **فشل في أحد الأنظمة اللاحقة** | استجابة 5xx، أو انتهاء مهلة، أو استجابة ناجحة تحمل خطأً من شركة الشحن. | أعد المحاولة مع زيادة فترات الانتظار (Backoff). قد يكون الطلب قد نجح جزئيًا، لذا اجعل تكراره آمنًا. |

> [!WARNING]
>
> **الشكل الثالث هو الأخطر**
>
> رفض شركة الشحن للحجز ليس خطأً من OTO، ولذلك لا يصل دائمًا بوصفه فشل HTTP. ببساطة، لا تُنشأ الشحنة ويبقى الطلب متوقفًا.
>
> وهذا تحديدًا هو غرض [Webhook](https://docs.tryoto.com/ar/developers/webhook-events.md) من نوع `shipmentError`: إذ يحمل `errorCode`، و`errorMessage` الخاصة بـ OTO، ونص رد شركة الشحن الخام في `deliveryCompanyResponse`، وغالبًا ما يكون السبب بسيطًا وقابلًا للإصلاح، مثل مدينة أو رمز بريدي ناقص. ومن دونه لا يعلم أحد بالمشكلة حتى يسأل العميل.

## إعادة المحاولة بأمان

* **لا تُعد محاولة طلبات الإنشاء عشوائيًا أبدًا.** الاستدعاءان `createOrder` و`createShipment` يغيّران الحالة. فإذا انتهت مهلة استدعاء، تحقق من وجود الكائن قبل إعادة إرساله، فاستدعاء `orderDetails` أقل تكلفة بكثير من شحنة مكررة.
* **زد فترات الانتظار أسّيًا.** إعادة المحاولة المتلاحقة على خدمة متعثرة تُفاقم المشكلة ولا تُسرّع شيئًا.
* **ضع حدًا أقصى للمحاولات ثم صعّد المشكلة.** الطلب الذي فشل خمس مرات يحتاج إلى شخص، لا إلى محاولة سادسة.
* **احتفظ بالطلبات الفاشلة.** جدول «dead-letter» للطلبات التي لم تنجح أبدًا هو ما يكشف لك النمط: شركة شحن واحدة، أو مدينة واحدة، أو منتج واحد بلا وزن.

## انتهاء صلاحية الرمز ليس خطأً

تبقى رموز الوصول صالحة لمدة ساعة، لذا ستواجه عملية الربط التي تعمل لفترات طويلة استجابة 401 بشكل اعتيادي. تعامل معها كإشارة لا كعطل: جدّد الرمز وأعد إرسال الطلب مرة واحدة. ولا تُطلق تنبيهًا إلا إذا فشل التجديد نفسه، لأن ذلك يعني أن بيانات الاعتماد خاطئة لا قديمة.

## حدود الاستخدام

الاستعلام المتكرر هو ما يوقع عملية الربط في المشكلات، وغالبًا ما يكون حلقة تسأل عن حالات طلبات لم تتغير. ويُزيل [Webhook](https://docs.tryoto.com/ar/developers/webhook-events.md) هذه الحلقة تمامًا، وهذا هو الحل الحقيقي. وإذا كان لا بد من الاستعلام، فاجعله محددًا: فلتر حسب التاريخ والحالة بدلًا من جلب كل شيء ثم المقارنة.

## مرجع الحالات ورموز الأخطاء

تتوفر القائمة الكاملة لحالات الطلبات ورموز أخطاء المنصة على [apis.tryoto.com](https://apis.tryoto.com)، تحت **List Of Statuses** و**Error Codes**. وكلتاهما تُولَّدان مع نقاط النهاية، لذا تبقيان متوافقتين مع ما تُعيده الواجهة فعليًا.

> [!TIP]
>
> **اربط الحالات مرة واحدة وفي مكان واحد**
>
> لن يستخدم نظامك وOTO المصطلحات نفسها، ومكان التحويل بينهما جدول ربط واحد، لا مقارنات نصية متناثرة في الكود.
>
> عند ظهور حالة جديدة، يتغير جدول واحد. والبديل هو البحث عن المواضع السبعة التي تتحقق من `delivered`.

## صفحات ذات صلة

* [أحداث Webhook](https://docs.tryoto.com/ar/developers/webhook-events.md) — حيث تظهر أخطاء الشحنات.
* [التوثيق](https://docs.tryoto.com/ar/developers/authentication.md) — مدة صلاحية الرمز وتجديده.
* [ربط شركات الشحن](https://docs.tryoto.com/ar/modules/shipping-management/carrier-integration.md) — لماذا ترفض شركة الشحن حجزًا.


## Related topics

- [نظرة عامة على OTO API](https://docs.tryoto.com/ar/developers/overview.md)
- [التوثيق في واجهة API](https://docs.tryoto.com/ar/developers/authentication.md)
- [مجموعة Postman لواجهة OTO API](https://docs.tryoto.com/ar/developers/postman-collection.md)


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