مرجع المطورين

رموز الخطأ

استكشف توثيق 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 في الشيفرة الجديدة.