API
رموز الأخطاء
مرجع التعامل مع أخطاء واجهة TBit API
# رموز الأخطاء > مرجع التعامل مع أخطاء واجهة TBit API - الصفحة: https://tbit.app/ar/docs/api/errors - عنوان URL الأساسي: `https://rest-api.tbit.app/v1` - المصادقة: ترويسة `X-API-Key` تحمل مفتاحك في كل طلب (تقرأه الأمثلة من متغير البيئة `TBIT_API_KEY`) هل تبحث عن سبب عدم تسليم رسالة واتساب؟ راجع [أخطاء التسليم في واتساب](https://tbit.app/docs/whatsapp-delivery-errors). ## صيغة استجابة الخطأ تتبع كل الأخطاء بنية JSON ثابتة: ```json { "error": { "code": "NOT_FOUND", "message": "Activity not found" } } ``` ## رموز الأخطاء | الحالة | الرمز | الوصف | | --- | --- | --- | | `400` | `VALIDATION_ERROR` | body الطلب أو معاملات الاستعلام غير صالحة | | `401` | `UNAUTHORIZED` | مفتاح API مفقود أو غير صالح | | `404` | `NOT_FOUND` | المورد غير موجود أو لا يخص وكيلك | | `405` | `METHOD_NOT_ALLOWED` | طريقة HTTP غير مدعومة في نقطة النهاية هذه | | `409` | `CONFLICT` | المورد موجود مسبقًا (مثل جهة اتصال بهذه القناة) | | `422` | `SEND_FAILED` | فشل إرسال القالب (مثل عدم وجود نافذة مراسلة مفتوحة) | | `429` | `RATE_LIMITED` | تم تجاوز حد معدّل الطلبات (100 طلب/دقيقة) | | `500` | `INTERNAL_ERROR` | خطأ غير متوقع في الخادم | ## ترويسات حد معدّل الطلبات كل استجابة تتضمن معلومات حد معدّل الطلبات في الترويسات: | الترويسة | الوصف | | --- | --- | | `X-RateLimit-Remaining` | الطلبات المتبقية في النافذة الحالية | | `X-RateLimit-Reset` | الطابع الزمني (بالمللي ثانية) الذي تُعاد فيه النافذة | ## التعامل مع الأخطاء أفضل الممارسات للتعامل مع أخطاء الـ API: - تحقّق دائمًا من رمز حالة HTTP قبل تحليل body الاستجابة - طبّق تراجعًا أُسّيًا (exponential backoff) لأخطاء 429 (حد معدّل الطلبات) - سجّل رموز الأخطاء ورسائلها لتسهيل التصحيح - لا تُعِد محاولة أخطاء 400 أو 401: صحّح الطلب أولًاهل تبحث عن سبب عدم تسليم رسالة واتساب؟ راجع أخطاء التسليم في واتساب.
تتبع كل الأخطاء بنية JSON ثابتة:
{
"error": {
"code": "NOT_FOUND",
"message": "Activity not found"
}
}| الحالة | الرمز | الوصف |
|---|---|---|
400 | VALIDATION_ERROR | body الطلب أو معاملات الاستعلام غير صالحة |
401 | UNAUTHORIZED | مفتاح API مفقود أو غير صالح |
404 | NOT_FOUND | المورد غير موجود أو لا يخص وكيلك |
405 | METHOD_NOT_ALLOWED | طريقة HTTP غير مدعومة في نقطة النهاية هذه |
409 | CONFLICT | المورد موجود مسبقًا (مثل جهة اتصال بهذه القناة) |
422 | SEND_FAILED | فشل إرسال القالب (مثل عدم وجود نافذة مراسلة مفتوحة) |
429 | RATE_LIMITED | تم تجاوز حد معدّل الطلبات (100 طلب/دقيقة) |
500 | INTERNAL_ERROR | خطأ غير متوقع في الخادم |
كل استجابة تتضمن معلومات حد معدّل الطلبات في الترويسات:
| الترويسة | الوصف |
|---|---|
X-RateLimit-Remaining | الطلبات المتبقية في النافذة الحالية |
X-RateLimit-Reset | الطابع الزمني (بالمللي ثانية) الذي تُعاد فيه النافذة |
أفضل الممارسات للتعامل مع أخطاء الـ API:
- تحقّق دائمًا من رمز حالة HTTP قبل تحليل body الاستجابة
- طبّق تراجعًا أُسّيًا (exponential backoff) لأخطاء 429 (حد معدّل الطلبات)
- سجّل رموز الأخطاء ورسائلها لتسهيل التصحيح
- لا تُعِد محاولة أخطاء 400 أو 401: صحّح الطلب أولًا