رموز الخطأ
استكشف توثيق API الخاص بـ رموز الخطأ، بما في ذلك معلمات الطلب وحقول الاستجابة وأمثلة الشفرة ومعالجة الأخطاء لتكاملات DomScan.
رموز الخطأ
الأخطاء المنظمة
يعيد كل خطأ في واجهة API الشكل نفسه من JSON: كائن error يتضمن code ثابتًا وmessage مقروءة وtype وحالة HTTP في status، وما إذا كان retryable، إضافة إلى request_id وdocs_url. يطابق request_id دائمًا رأس الرد X-Request-Id، فأدرجه عند التواصل مع الدعم.
{
"error": {
"code": "INVALID_DOMAIN",
"message": "تنسيق نطاق غير صالح",
"suggestion": "استخدم نطاقًا قابلًا للتسجيل مثل example.com",
"type": "validation_error",
"status": 400,
"retryable": false,
"request_id": "m5x7k2p-a9f3",
"docs_url": "https://domscan.net/docs/check-availability"
}
}
حقول الخطأ
| الحقل | الوصف |
|---|---|
code | رمز خطأ ثابت يمكن للآلة قراءته. لا تتم إعادة تسمية الرموز أبدًا، لذلك يمكنك الاعتماد عليها بأمان في منطق التفرع. |
message | شرح مقروء للخطأ. قد تتغير صياغته، لذلك لا تحلله برمجيًا. |
type | الفئة العامة التي ينتمي إليها الخطأ، وهي تشير إلى طبيعة المشكلة، مثل validation_error أو authentication_error أو rate_limit_error. |
status | رمز حالة HTTP، يتكرر في نص الرد لتسهيل السجلات وقوائم الانتظار. |
retryable | يحدد ما إذا كان الطلب نفسه قد ينجح إذا أعدت المحاولة لاحقًا. |
request_id | معرّف فريد للطلب. يطابق الرأس X-Request-Id. |
docs_url | رابط إلى قسم التوثيق الذي يشرح هذا الخطأ. |
suggestion | تلميح اختياري حول كيفية تصحيح الطلب. |
details | سياق منظم اختياري، مثل الطرق المسموح بها أو المعلمة غير الصالحة. |
retry_after | عدد اختياري من الثواني التي يجب انتظارها قبل إعادة المحاولة. يُرسل أيضًا في الرأس Retry-After. |
رموز الخطأ الشائعة
هذه هي الرموز التي يحتاج معظم العملاء إلى التعامل معها. تعيد بعض نقاط النهاية رموزًا أكثر تحديدًا تتبع القواعد نفسها؛ والقائمة الكاملة مع الحالة والنوع وسلوك إعادة المحاولة موجودة في مواصفات OpenAPI ضمن x-domscan-error-codes. ما زال الرمز RATE_LIMIT_EXCEEDED مقبولًا كاسم بديل للرمز RATE_LIMITED.
| الرمز | حالة الاستجابة (HTTP) | النوع | قابل لإعادة المحاولة | الوصف |
|---|---|---|---|---|
BAD_REQUEST |
400 | validation_error |
لا | معلمات مفقودة أو غير صالحة |
MISSING_PARAMETER |
400 | validation_error |
لا | معلمة مطلوبة مفقودة |
INVALID_PARAMETER |
400 | validation_error |
لا | قيمة إحدى المعلمات غير صالحة |
INVALID_JSON |
400 | validation_error |
لا | نص الطلب ليس JSON صالحًا |
INVALID_DOMAIN |
400 | validation_error |
لا | تنسيق نطاق غير صالح |
UNSUPPORTED_TLD |
400 | validation_error |
لا | TLD غير مدعوم |
SUBDOMAIN_NOT_SUPPORTED |
400 | validation_error |
لا | تقبل نقطة النهاية هذه النطاقات القابلة للتسجيل، وليس النطاقات الفرعية |
VALIDATION_ERROR |
422 | validation_error |
لا | الطلب سليم التركيب لكن لا يمكن معالجته |
AUTH_REQUIRED |
401 | authentication_error |
لا | لم يتم تقديم مفتاح API أو جلسة |
INVALID_API_KEY |
401 | authentication_error |
لا | مفتاح API غير صالح أو تم إلغاؤه |
INSUFFICIENT_CREDITS |
402 | credits_error |
لا | لا يملك حسابك أرصدة كافية لهذا الطلب |
FORBIDDEN |
403 | permission_error |
لا | ليس لديك إذن لتنفيذ هذا الإجراء |
NOT_FOUND |
404 | not_found_error |
لا | نقطة النهاية أو المورد غير موجود |
METHOD_NOT_ALLOWED |
405 | request_error |
لا | نقطة النهاية موجودة لكنها لا تقبل طريقة HTTP هذه. يسرد الرأس Allow الطرق المدعومة. |
CONFLICT |
409 | conflict_error |
لا | الطلب يتعارض مع الحالة الحالية للمورد |
IDEMPOTENCY_CONFLICT |
409 | conflict_error |
لا | سبق استخدام مفتاح عدم التكرار (idempotency) مع طلب مختلف |
IDEMPOTENCY_KEY_REUSED |
422 | validation_error |
لا | سبق استخدام Idempotency-Key هذا مع طلب مختلف خلال آخر 24 ساعة. استخدم مفتاحاً جديداً للطلب الجديد. |
IDEMPOTENCY_IN_PROGRESS |
409 | conflict_error |
نعم | لا يزال الطلب الذي يحمل Idempotency-Key هذا قيد التشغيل. أعد المحاولة بعد قليل للحصول على استجابته المخزنة. |
RATE_LIMITED |
429 | rate_limit_error |
نعم | طلبات كثيرة جداً |
INTERNAL |
500 | api_error |
لا | خطأ غير متوقع في الخادم. إذا استمر، تواصل مع الدعم مع ذكر معرّف الطلب. |
UPSTREAM_ERROR |
502 | upstream_error |
نعم | أعاد مصدر بيانات خارجي ردًا غير قابل للاستخدام |
UPSTREAM_UNAVAILABLE |
503 | upstream_error |
نعم | مصدر بيانات خارجي غير متاح مؤقتًا |
SERVICE_UNAVAILABLE |
503 | upstream_error |
نعم | الخدمة غير متاحة مؤقتًا |
TIMEOUT |
504 | timeout_error |
نعم | لم يستجب مصدر بيانات خارجي أو سجل في الوقت المناسب |
إرشادات إعادة المحاولة
- أعد المحاولة فقط عندما تكون قيمة
retryableهيtrue. أما في أخطاء التحقق والمصادقة والصلاحيات، فصحّح الطلب أولًا. - عند وجود
retry_afterأو الرأسRetry-After، انتظر هذا العدد من الثواني على الأقل قبل المحاولة التالية. - وإلا فاستخدم التراجع الأسي مع تباين عشوائي، مثل 1 و2 و4 و8 ثوانٍ، وتوقف بعد عدة محاولات.
- عند إنشاء الدفعات والمهام، أرسل الرأس
Idempotency-Keyحتى لا ينشئ الطلب المعاد إرساله مهمة مكررة. - في طلبات POST الأخرى التي تخصم رصيداً، يجعل رأس
Idempotency-Keyإعادة المحاولة تُرجع الاستجابة المخزنة بدلاً من الخصم مرة أخرى.
التوافق
منذ 10 أكتوبر 2026 تستخدم كل نقاط النهاية هذا التنسيق. أما الحقول التي كانت بعض نقاط النهاية تعيدها أصلًا، مثل credits_remaining وpurchase_url وlogin_url وsuccess وmeta، فستبقى خلال فترة توافق، لذا تستمر عمليات الدمج الحالية في العمل. اقرأ تفاصيل الخطأ من الكائن error في الشيفرة الجديدة.