تعيد كل أخطاء API جسم JSON يحتوي على حقل error. تتطلب استجابة 4xx عادة تصحيح الطلب أو الحساب أو الحد؛ أما 5xx فتعني مشكلة خادمية أو مؤقتة، لكن أمان إعادة المحاولة يظل معتمدًا على الإجراء.
| الرمز | الاسم | المعنى |
|---|---|---|
| 400 | Bad Request | فشل التحقق لأن قيمة مطلوبة مفقودة أو مشوهة أو غير مدعومة أو خارج النطاق المسموح. صحح الطلب قبل إعادة المحاولة. |
| 403 | Forbidden | لا يُسمح للمفتاح أو الحساب بتنفيذ هذا الإجراء، مثلًا عند تعليق الحساب. لن تفيد إعادة المحاولة من دون تغيير. |
| 404 | Not Found | لم يُعثر على مورد API المطلوب أو أنه غير متاح لهذا المفتاح. تحقق من المعرّف وملكية الحساب قبل إعادة المحاولة. |
| 409 | Conflict | يتعارض الطلب مع الحالة القائمة، مثل إعادة استخدام request_id لإجراء add لطلب منطقي مختلف. استخدم الطلب الأصلي أو معرّفًا فريدًا جديدًا حسب الحالة. |
| 413 | Content Too Large | جسم الطلب كبير جدًا. قلّل الحمولة أو قسّم طلبات الدفعات المدعومة قبل إعادة المحاولة. |
| 429 | Too Many Requests | رفض حد للمعدل أو الإجراء الطلب. افحص X-RateLimit-DeniedBy عند وجوده وانتظر عدد الثواني النسبي في X-RateLimit-Reset. |
| 500 | Internal Server Error | حدث عطل خادمي غير متوقع. لا تفترض أن تكرار كل كتابة آمن؛ اتبع إرشادات إعادة المحاولة والتوفيق الخاصة بالإجراء. |
| 502 | Bad Gateway | رفض المزوّد طلب تنفيذ الخدمة. راجع توفر الخدمة وبيانات الطلب قبل إعادة المحاولة. |
| 503 | Service Unavailable | واجهة API أو عملية مطلوبة غير متاحة مؤقتًا، بما في ذلك عدم توفر مزود مؤهل (provider_not_found). أعد المحاولة لاحقًا بتراجع، واحترم Retry-After عند وجوده، واحتفظ بمعرّف التكرار الآمن نفسه عندما يدعم الإجراء ذلك. |
{
"error": "Missing required parameter: service"
}يتطلب الإجراء معاملًا لم يُدرَج. أضفه إلى جسم الطلب وأعد المحاولة.
{
"error": "Invalid API key"
}مفتاح خاطئ، أو مفتاح مُبطَل، أو مفتاح مفقود. تحقق من أن القيمة تطابق ما هو معروض في /dashboard/api. الخطأ متطابق للمفتاح المفقود والمفتاح غير الصالح لمنع هجمات التعداد.
{
"error": "Insufficient balance"
}رصيد حسابك أقل من إجمالي تكلفة الطلب. اشحن الرصيد عبر /dashboard/wallet، أو طبّق كوبونًا.
{
"error": "Service not found"
}معرّف الخدمة غير موجود. حدّث الكتالوج عبر action=services واختر معرّفًا حاليًا؛ الخدمات المتوقفة تستخدم خطأ 400 منفصلًا.
{
"error": "Rate limit exceeded"
}رفض حد للمعدل أو الإجراء الطلب. افحص X-RateLimit-DeniedBy عند وجوده وانتظر عدد الثواني النسبي في X-RateLimit-Reset.
{
"error": "language must be one of en, es, pt, ru, tr, ar, hi, id, fr, zh",
"error_code": "INVALID_LANGUAGE"
}تقبل services وcatalog الرموز en وes وpt وru وtr وar وhi وid وfr وzh فقط. صحّح قيمة اللغة قبل إعادة المحاولة.
أعِد محاولة action=add باستخدام request_id نفسه والطلب المنطقي نفسه لتجنب التكرار؛ واستخدم قيمة فريدة جديدة لطلب مختلف. يمكن تكرار إجراءات القراءة بأمان. وتبقى إعادة محاولة الإلغاء آمنة ما دام الطلب مؤهلاً للإلغاء.