الأخطاء وحدود المعدل
مرجع كامل لأكواد الخطأ، تعيين حالات HTTP، سياسات حد المعدل واستراتيجيات إعادة المحاولة.
أكواد حالة HTTP
API REST الحديثة تستخدم أكواد حالة HTTP القياسية. جسم الاستجابة يتضمن كائن خطأ منظم.
| الكود | الحالة | المعنى |
|---|---|---|
| 400 | Bad Request | فشل التحقق من الطلب (معاملات مفقودة أو غير صالحة) |
| 401 | Unauthorized | المصادقة مطلوبة أو مفتاح API غير صالح |
| 402 | Payment Required | رصيد محفظة غير كافٍ لإكمال الإجراء |
| 403 | Forbidden | تمت المصادقة، لكن غير مصرح بالوصول إلى هذا المورد |
| 404 | Not Found | المورد غير موجود (مثلاً معرف التفعيل غير موجود) |
| 409 | Conflict | الطلب يتعارض مع الحالة الحالية |
| 422 | Unprocessable Entity | الطلب صحيح الشكل لكن غير صالح دلالياً |
| 429 | Too Many Requests | تجاوز حد المعدل — راجع رأس Retry-After |
| 500 | Internal Server Error | خطأ خادم غير متوقع — أعد المحاولة بـ exponential backoff |
| 503 | Service Unavailable | المزود الخارجي غير متاح — أعد المحاولة لاحقاً |
شكل استجابة الخطأ (JSON)
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 27937
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-05-10T00:00:00.000Z
{
"error": "rate_limit_exceeded",
"message": "Daily API limit reached. Contact support for higher tier.",
"retryAfter": 27937,
"limit": 10000,
"usage": 10000
}أكواد SMS-Activate النصية
نقطة النهاية المتوافقة مع SMS-Activate تعيد أكواد نصية. كل كود يُعيَّن إلى حالة HTTP.
| كود نصي | HTTP | المعنى |
|---|---|---|
| BAD_KEY | 401 | مفتاح API غير صالح أو مفقود |
| BAD_ACTION | 400 | معامل action مفقود أو خاطئ |
| BAD_SERVICE | 400 | كود الخدمة غير معروف |
| BAD_COUNTRY | 400 | معامل country غير معروف |
| BAD_STATUS | 400 | قيمة status غير صالحة لـ setStatus |
| WRONG_ACTION | 400 | اسم الإجراء غير مدعوم |
| NO_BALANCE | 402 | رصيد المحفظة غير كافٍ |
| NO_NUMBERS | 404 | لا توجد أرقام متاحة لهذه التركيبة |
| NO_ACTIVATION | 404 | معرف التفعيل غير موجود أو ليس ملكك |
| RATE_LIMITED | 429 | تجاوز حد المعدل — تباطأ أو انتظر إعادة الضبط |
| ERROR_SQL | 500 | خطأ خادم داخلي — أعد المحاولة لاحقاً |
حدود المعدل
حصة لكل مفتاح API. خوادم متعددة بمفتاح واحد تتشارك دلواً واحداً.
حدود الدفعات
ثلاث طبقات حدود متزامنة تحمي من الدفعات والإساءة المستدامة. الوصول إلى أي طبقة يُعيد 429.
الحصة اليومية
افتراضياً 10,000 طلب لكل مفتاح API يومياً. تُعاد التهيئة عند منتصف الليل UTC.
- نقاط نهاية الكتالوج العامة (الخدمات، الدول) معفاة من الحصة اليومية
- العداد يزيد عند كل طلب مصادق عليه، بغض النظر عن حالة الاستجابة
- طبقة Pro بحدود أعلى متاحة — تواصل مع الدعم
ترويسات الاستجابة
كل استجابة API مصادقة تتضمن ترويسات حد المعدل كي تستطيع العملاء التحكم الذاتي.
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9543
X-RateLimit-Reset: 2026-05-10T00:00:00.000Z
Retry-After: 27937استراتيجية إعادة المحاولة
كيفية التعامل مع الإخفاقات العابرة دون إغراق API أو فقدان البيانات.
افعل
- • احترم رأس Retry-After في استجابات 429
- • استخدم exponential backoff لأخطاء 5xx (1ث، 2ث، 4ث، 8ث)
- • أعد المحاولة حتى 5 مرات، ثم أظهر الخطأ للمستخدم
لا تفعل
- • لا تعيد محاولة أخطاء 4xx غير 429 — فهي حتمية
- • لا تضرب API بعد 429 — انتظر فترة Retry-After كاملة
- • لا تعيد POST /activations دون فحص idempotency
نمط إعادة المحاولة الموصى به
# Pseudocode — exponential backoff with Retry-After
attempt = 0
while attempt < 5:
response = call_api()
if response.status == 200:
break # success
if response.status == 429:
wait = response.headers.get('Retry-After', 2 ** attempt)
sleep(wait)
attempt += 1
continue
if response.status >= 500:
sleep(2 ** attempt) # exponential
attempt += 1
continue
raise APIError(response) # 4xx other than 429Idempotency
بعض العمليات تُحمِّل محفظتك — إعادة المحاولة الساذجة قد تُسبب رسوماً مزدوجة.
POST /activations ليس idempotent
إذا أعدت محاولة POST /activations ناجحة، ستُنشئ تفعيلاً ثانياً وتُحمَّل مرتين. عند أي مهلة أو استجابة غير واضحة، استخدم GET /activations للتحقق من الحالة قبل إعادة المحاولة.
تحتاج تفاصيل أكثر؟
مرجع API التفاعلي يُظهر استجابات الأخطاء لكل نقطة نهاية.