الأخطاء

كل خطأ بالشكل نفسه:

{
  "error": {
    "type": "invalid_request",
    "code": "unknown_parameter",
    "message": "Unknown parameter 'bed'.",
    "param": "bed",
    "request_id": "req_4f1c2d9a8b7e6f5a4b3c2d1e",
    "doc_url": "https://platform.darak.app/docs/guides/errors#unknown-parameter"
  }
}

اعتمد في التفرّع على code: لا تُعاد تسمية الرموز، لكن قد تُضاف رموز جديدة. message للبشر وقد تتغير. معاملات الاستعلام غير المعروفة أخطاء وليست متجاهلة، فتظهر الأخطاء الإملائية فورًا. اذكر request_id عند التواصل معنا.

400 `invalid_request`

الطلب غير صحيح. أصلحه؛ ستفشل إعادته دون تغيير بالطريقة نفسها.

invalid_value: قيمة معامل غير مقبولة. يحدد param المعامل.
missing_parameter: لم يُرسل معامل مطلوب. يحدد param المعامل.
unknown_parameter: المعامل غير موجود. تُرفض المعاملات غير المعروفة ولا تُتجاهل لتظهر الأخطاء الإملائية.
invalid_body: جسم JSON غير سليم أو لا يطابق المخطط.
unknown_city: المدينة غير مغطاة. يسرد GET /cities أسماء المدن المقبولة.
result_window_exceeded: تجاوزت عمق تصفح خطتك. ضيّق الاستعلام بدلًا من ذلك.
limit_reached: بلغ أحد حدود الحساب أقصاه.
invalid_cursor: المؤشر غير سليم أو يخص استعلامًا بمرشّحات أو ترتيب مختلف. ابدأ الاستعلام مجددًا.

401 `authentication_error`

المفتاح مفقود أو غير سليم أو لم يعد صالحًا. لا تُعد المحاولة.

missing_api_key: ترويسة Authorization: Bearer مفقودة.
invalid_api_key: لا يوجد مفتاح مطابق. تحقق من أن المفتاح كامل ومن البيئة الصحيحة.
revoked_api_key: أُلغي هذا المفتاح. أنشئ مفتاحًا جديدًا.
expired_api_key: انتهت صلاحية هذا المفتاح. أنشئ مفتاحًا جديدًا.
api_key_in_query: أُرسل المفتاح في الرابط حيث يتسرّب إلى السجلات. انقله للترويسة ودوّره.

403 `permission_error`

المفتاح صالح، لكنه غير مخوّل لهذا الطلب. لا تُعد المحاولة.

scope_not_in_plan: لا تشمل خطتك هذه الواجهة. رقِّ الخطة للوصول إليها.
scope_not_in_key: تشمل خطتك الواجهة لكن المفتاح غير مخوّل لها. عدّل المفتاح.
admin_key_required: تتطلب نقطة النهاية مفتاح إدارة (dk_admin_…).
admin_key_not_allowed: مفاتيح الإدارة تصل فقط إلى /v1/organization. استخدم مفتاح بيانات هنا.
forbidden_action: لا يسمح دورك في المؤسسة بهذا الإجراء.
cr_outside_allowlist: السجل التجاري غير مدرج في قائمة السماح لحسابك.
ip_not_allowed: عنوان المتصل غير مدرج في قائمة عناوين IP المسموحة للمؤسسة.
client_suspended: الحساب معلّق. تواصل معنا.
client_expired: انتهت مدة الحساب. تواصل معنا.

404 `not_found`

المورد غير موجود. وقد يكون الإعلان لم يعد نشطًا.

not_found: المورد غير موجود.
city_not_found: المدينة غير موجودة. يسرد GET /cities المدن.
route_not_found: نقطة النهاية غير موجودة. المواصفة في /v1/openapi.json.
listing_not_found: لا يوجد إعلان نشط بهذا المعرّف. قد يكون أُزيل.
neighborhood_not_found: لا يوجد حي بهذا المعرّف في المدينة.
project_not_found: المشروع على الخارطة غير موجود.
period_not_found: لم ينشر المصدر بيانات للفترة. يسرد details.available_periods الفترات المتاحة.
release_not_found: لا يوجد إصدار منشور مطابق من مؤشر دارك العقاري. يسرد details.available_releases الإصدارات.
export_not_found: لا يوجد تصدير بهذا المعرّف للمؤسسة. تُحفظ سجلات التصدير 90 يومًا وملفاته 7 أيام.

405 `method_not_allowed`

المسار صحيح وطريقة HTTP غير صحيحة. تسرد Allow الطرق المقبولة.

method_not_allowed: المسار موجود، لكن ليس لهذه الطريقة.

409 `conflict`

لا يمكن تطبيق الطلب في الحالة الحالية. غيّره ثم أعد المحاولة.

conflict: تمنع حالة المورد الحالية هذا الإجراء.
idempotency_key_reuse: استُخدم Idempotency-Key مع جسم مختلف. استخدم مفتاحًا جديدًا.
key_limit: بلغت أقصى عدد مفاتيح لخطتك. ألغِ مفتاحًا أولًا.
project_limit: بلغت أقصى عدد مشاريع لخطتك.
name_taken: يوجد عنصر بهذا الاسم بالفعل.
export_limit: هناك صادرات كثيرة قيد التنفيذ أو أُنشئت اليوم. انتظر اكتمال أحدها؛ يحدد details الحد.

429 `rate_limit_error`

خفّض المعدل. تحدد Retry-After مدة الانتظار.

rate_limited: تجاوزت معدل الوحدات في الدقيقة. انتظر عدد الثواني في Retry-After.
monthly_quota_exceeded: نفدت حصة وحدات الشهر. تتجدد في بداية الشهر التالي بتوقيت UTC، أو ارفع سقف الإنفاق.
spend_cap_reached: بلغ الاستخدام الإضافي سقف الإنفاق الشهري الذي حدده المالك. ارفعه للمتابعة.
project_cap_exceeded: بلغ مشروع المفتاح سقف وحداته الشهري.

500 `api_error`

الخطأ من جانبنا. أعد المحاولة مع تراجع أُسّي.

internal_error: حدث خلل من جانبنا. أعد المحاولة مع تراجع؛ واذكر request_id إذا استمر.

يمكن إعادة محاولة أخطاء 5xx بأمان مع تراجع أُسّي.

الأخطاء

كل خطأ بالشكل نفسه:

{
  "error": {
    "type": "invalid_request",
    "code": "unknown_parameter",
    "message": "Unknown parameter 'bed'.",
    "param": "bed",
    "request_id": "req_4f1c2d9a8b7e6f5a4b3c2d1e",
    "doc_url": "https://platform.darak.app/docs/guides/errors#unknown-parameter"
  }
}

400 `invalid_request`

الطلب غير صحيح. أصلحه؛ ستفشل إعادته دون تغيير بالطريقة نفسها.

invalid_value: قيمة معامل غير مقبولة. يحدد param المعامل.
missing_parameter: لم يُرسل معامل مطلوب. يحدد param المعامل.
unknown_parameter: المعامل غير موجود. تُرفض المعاملات غير المعروفة ولا تُتجاهل لتظهر الأخطاء الإملائية.
invalid_body: جسم JSON غير سليم أو لا يطابق المخطط.
unknown_city: المدينة غير مغطاة. يسرد GET /cities أسماء المدن المقبولة.
result_window_exceeded: تجاوزت عمق تصفح خطتك. ضيّق الاستعلام بدلًا من ذلك.
limit_reached: بلغ أحد حدود الحساب أقصاه.
invalid_cursor: المؤشر غير سليم أو يخص استعلامًا بمرشّحات أو ترتيب مختلف. ابدأ الاستعلام مجددًا.

401 `authentication_error`

المفتاح مفقود أو غير سليم أو لم يعد صالحًا. لا تُعد المحاولة.

missing_api_key: ترويسة Authorization: Bearer مفقودة.
invalid_api_key: لا يوجد مفتاح مطابق. تحقق من أن المفتاح كامل ومن البيئة الصحيحة.
revoked_api_key: أُلغي هذا المفتاح. أنشئ مفتاحًا جديدًا.
expired_api_key: انتهت صلاحية هذا المفتاح. أنشئ مفتاحًا جديدًا.
api_key_in_query: أُرسل المفتاح في الرابط حيث يتسرّب إلى السجلات. انقله للترويسة ودوّره.

403 `permission_error`

المفتاح صالح، لكنه غير مخوّل لهذا الطلب. لا تُعد المحاولة.

scope_not_in_plan: لا تشمل خطتك هذه الواجهة. رقِّ الخطة للوصول إليها.
scope_not_in_key: تشمل خطتك الواجهة لكن المفتاح غير مخوّل لها. عدّل المفتاح.
admin_key_required: تتطلب نقطة النهاية مفتاح إدارة (dk_admin_…).
admin_key_not_allowed: مفاتيح الإدارة تصل فقط إلى /v1/organization. استخدم مفتاح بيانات هنا.
forbidden_action: لا يسمح دورك في المؤسسة بهذا الإجراء.
cr_outside_allowlist: السجل التجاري غير مدرج في قائمة السماح لحسابك.
ip_not_allowed: عنوان المتصل غير مدرج في قائمة عناوين IP المسموحة للمؤسسة.
client_suspended: الحساب معلّق. تواصل معنا.
client_expired: انتهت مدة الحساب. تواصل معنا.

404 `not_found`

المورد غير موجود. وقد يكون الإعلان لم يعد نشطًا.

not_found: المورد غير موجود.
city_not_found: المدينة غير موجودة. يسرد GET /cities المدن.
route_not_found: نقطة النهاية غير موجودة. المواصفة في /v1/openapi.json.
listing_not_found: لا يوجد إعلان نشط بهذا المعرّف. قد يكون أُزيل.
neighborhood_not_found: لا يوجد حي بهذا المعرّف في المدينة.
project_not_found: المشروع على الخارطة غير موجود.
period_not_found: لم ينشر المصدر بيانات للفترة. يسرد details.available_periods الفترات المتاحة.
release_not_found: لا يوجد إصدار منشور مطابق من مؤشر دارك العقاري. يسرد details.available_releases الإصدارات.
export_not_found: لا يوجد تصدير بهذا المعرّف للمؤسسة. تُحفظ سجلات التصدير 90 يومًا وملفاته 7 أيام.

405 `method_not_allowed`

المسار صحيح وطريقة HTTP غير صحيحة. تسرد Allow الطرق المقبولة.

method_not_allowed: المسار موجود، لكن ليس لهذه الطريقة.

409 `conflict`

لا يمكن تطبيق الطلب في الحالة الحالية. غيّره ثم أعد المحاولة.

conflict: تمنع حالة المورد الحالية هذا الإجراء.
idempotency_key_reuse: استُخدم Idempotency-Key مع جسم مختلف. استخدم مفتاحًا جديدًا.
key_limit: بلغت أقصى عدد مفاتيح لخطتك. ألغِ مفتاحًا أولًا.
project_limit: بلغت أقصى عدد مشاريع لخطتك.
name_taken: يوجد عنصر بهذا الاسم بالفعل.
export_limit: هناك صادرات كثيرة قيد التنفيذ أو أُنشئت اليوم. انتظر اكتمال أحدها؛ يحدد details الحد.

429 `rate_limit_error`

خفّض المعدل. تحدد Retry-After مدة الانتظار.

rate_limited: تجاوزت معدل الوحدات في الدقيقة. انتظر عدد الثواني في Retry-After.
monthly_quota_exceeded: نفدت حصة وحدات الشهر. تتجدد في بداية الشهر التالي بتوقيت UTC، أو ارفع سقف الإنفاق.
spend_cap_reached: بلغ الاستخدام الإضافي سقف الإنفاق الشهري الذي حدده المالك. ارفعه للمتابعة.
project_cap_exceeded: بلغ مشروع المفتاح سقف وحداته الشهري.

500 `api_error`

الخطأ من جانبنا. أعد المحاولة مع تراجع أُسّي.

internal_error: حدث خلل من جانبنا. أعد المحاولة مع تراجع؛ واذكر request_id إذا استمر.

يمكن إعادة محاولة أخطاء 5xx بأمان مع تراجع أُسّي.

الأخطاء

400 invalid_request

401 authentication_error

403 permission_error

404 not_found

405 method_not_allowed

409 conflict

429 rate_limit_error

500 api_error

الأخطاء

400 invalid_request

401 authentication_error

403 permission_error

404 not_found

405 method_not_allowed

409 conflict

429 rate_limit_error

500 api_error

400 `invalid_request`

401 `authentication_error`

403 `permission_error`

404 `not_found`

405 `method_not_allowed`

409 `conflict`

429 `rate_limit_error`

500 `api_error`

400 `invalid_request`

401 `authentication_error`

403 `permission_error`

404 `not_found`

405 `method_not_allowed`

409 `conflict`

429 `rate_limit_error`

500 `api_error`