> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/ar/docs/error-codes

# رموز الخطأ

استكشف توثيق API الخاص بـ رموز الخطأ، بما في ذلك معلمات الطلب وحقول الاستجابة وأمثلة الشفرة ومعالجة الأخطاء لتكاملات DomScan.

### الأخطاء المنظمة

يعيد كل خطأ في واجهة API الشكل نفسه من JSON: كائن `error` يتضمن `code` ثابتًا و`message` مقروءة و`type` وحالة HTTP في `status`، وما إذا كان `retryable`، إضافة إلى `request_id` و`docs_url`. يطابق `request_id` دائمًا رأس الرد `X-Request-Id`، فأدرجه عند التواصل مع الدعم.

```json
{
  "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` في الشيفرة الجديدة.
