# رموز الأخطاء

> مرجع التعامل مع أخطاء واجهة 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: صحّح الطلب أولًا