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

# الرصد واستكشاف الأخطاء

> سجل معرفات TokenLab العامة المطلوبة للدعم، تسوية الاستخدام، واستكشاف الأخطاء في الوسائط غير المتزامنة.

يبدأ رصد TokenLab الجيد بالمعرفات العامة. يجب أن تساعدك سجلاتك في الإجابة على "ما الذي طلبه المستخدم، وما هي المهمة العامة التي أنشأها TokenLab، وكيف تم الفوترة؟" دون الكشف عن تفاصيل توجيه المزود أو بيانات المستخدم الحساسة.

## المعرفات العامة التي يجب التقاطها

| المعرف                         | مكان ظهوره                                                                                                       | استخدمه لـ                                                   |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `request_id`                   | أجسام الأخطاء، سجلات لوحة التحكم، سجلات الاستخدام                                                                | دعم على مستوى الطلب وتسوية                                   |
| `id` / `task_id`               | استجابات الإنشاء غير المتزامن والحالة                                                                            | استعلام عن الصور، الفيديو، الموسيقى، والوظائف ثلاثية الأبعاد |
| `poll_url`                     | استجابات الإنشاء غير المتزامن                                                                                    | عنوان URL للحالة المفضلة                                     |
| `billing_transaction_id`       | استجابات غير متدفقة عند التسوية، استجابات حالة المهمة غير المتزامنة، سجلات الاستخدام، `X-Billing-Transaction-ID` | تسوية التكلفة                                                |
| `X-Task-ID`                    | رؤوس استجابة المهمة غير المتزامنة                                                                                | ارتباط المهمة على مستوى الرأس                                |
| معرف الوظيفة/المستخدم الخاص بك | تطبيقك                                                                                                           | ربط نشاط TokenLab بتدفق عمل المستخدم                         |

لا تخزن معرفات مهام المزود، عناوين URL العلوية، معرفات قنوات التوجيه، مفاتيح Redis، أو بيانات التنفيذ الخاصة كحقائق موجهة للعملاء.

## ما يجب تسجيله

سجل ما يكفي لتشخيص الطلب دون تسريب الأسرار:

* نقطة النهاية، طريقة HTTP، النموذج، رمز الحالة، الطابع الزمني، والكمون.
* المعرفات العامة: `request_id`، `task_id`، `poll_url`، و `billing_transaction_id` عند وجودها.
* شكل الطلب المنقح: أي الحقول كانت موجودة، وليس النص الكامل أو محتوى الوسائط الخاصة.
* استجابات الحالة غير المتزامنة النهائية، بما في ذلك حقول الخطأ العامة.
* عدد محاولات إعادة الاتصال من العميل وما إذا كانت إعادة الاتصال قد أنشأت مهمة جديدة أو استأنفت واحدة موجودة.

قم دائمًا بحجب `Authorization`، مفاتيح API، رموز الإدارة، عناوين URL الموقعة، عناوين URL الوسائط الخاصة، النصوص الكاملة، وبيانات المستخدم الشخصية ما لم يكن لديك إذن صريح للاحتفاظ بها.

## مصفوفة استكشاف الأخطاء

| العرض                                   | تحقق أولاً                                                                 | صفحة مفيدة                                                       |
| --------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `401` أو `403`                          | مفتاح API، رمز الإدارة، وصول المؤسسة، نطاق المفتاح                         | [المصادقة](/ar/authentication)                                   |
| `402`                                   | الرصيد، حد إنفاق مفتاح API، توفر سعر النموذج                               | [الفوترة والتسعير](/ar/guides/billing)                           |
| `429`                                   | مستوى الحساب، حد معدل نقطة النهاية، سلوك إعادة المحاولة                    | [حدود المعدل](/ar/guides/rate-limits)                            |
| `400 invalid_request_error`             | حقل غير مدعوم، نقطة نهاية خاطئة، حقل مطلوب مفقود، أو عدم تطابق عقد النموذج | [معالجة الأخطاء](/ar/guides/error-handling)                      |
| لا يمكن العثور على المهمة غير المتزامنة | مفتاح API خاطئ، معرف مهمة قديم، مهمة منتهية، أو معرف مهمة غير عام          | [المهام غير المتزامنة والاستعلام](/ar/guides/async-jobs-polling) |
| التكلفة لا تتطابق مع واجهة المستخدم     | توقيت التسوية أو مقارنة المعرف الخاطئ                                      | [الفوترة والتسعير](/ar/guides/billing)                           |

## تسوية الاستخدام

استخدم واجهة إدارة API للتسوية من جانب الخادم:

```bash theme={null}
curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video" \
  -H "Authorization: Bearer mt-your-management-token"
```

`GET /v1/management/api-keys/{keyId}/usage` يمكن أن يقوم بالتصفية حسب `scene`، `accessChannel`، `logicalModel`، `modelVendor`، `startDate`، و `endDate`. استخدم هذه السجلات بدلاً من جمع بيانات صفحات لوحة التحكم أو الاعتماد على معرفات مهام المزود العلوية.

قد تستقر الاستجابات المتدفقة بعد إرسال التدفق، لذا قد يكون رأس الفوترة غائبًا حتى عندما يتم تسجيل الاستخدام لاحقًا. قد تستقر المهام الإعلامية غير المتزامنة بعد الاستعلام النهائي.

## قالب حزمة الدعم

عند الاتصال بالدعم، قم بتضمين:

* `request_id`.
* `task_id` و `poll_url` للعمل غير المتزامن.
* `billing_transaction_id` عند وجوده.
* نقطة النهاية، الطريقة، النموذج، الطابع الزمني، ورمز الحالة.
* شكل الطلب المنقح وجسم الخطأ العام.
* النتيجة المتوقعة وما رآه المستخدم فعليًا.

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

## الفحوصات التشغيلية

* تنبيه على تكرار الاستجابات `401`، `402`، `429`، و `5xx` بشكل منفصل؛ عادةً ما يكون لها مالكون مختلفون.
* تتبع المهام غير المتزامنة التي تبقى غير نهائية لفترة أطول من SLA المنتج الخاص بك.
* تتبع محاولات الإنشاء المكررة لنفس معرف وظيفة المستخدم.
* عيّن عينة من الوظائف المكتملة وتحقق من أن الأصل المرئي للمستخدم، سجل الاستخدام، وسجل المهمة المخزنة تتفق.

## مرجع API

| الموضوع                      | المرجع                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------ |
| معالجة الأخطاء               | [معالجة الأخطاء](/ar/guides/error-handling)                                    |
| حدود المعدل                  | [حدود المعدل](/ar/guides/rate-limits)                                          |
| الفوترة والتسعير             | [الفوترة والتسعير](/ar/guides/billing)                                         |
| الحصول على استخدام مفتاح API | [الحصول على استخدام مفتاح API](/ar/api-reference/management/get-api-key-usage) |
| الحصول على حالة المهمة       | [الحصول على حالة المهمة](/ar/api-reference/tasks/get-task-status)              |