الأخطاء

شكلٌ واحدٌ ثابتٌ لكلّ خطأ، ورمزٌ قابلٌ للقراءة آلياً. وكلُّ ردٍّ يحمل رابطَه إلى هذه الصفحة وإلى موضعِ رمزِه فيها.

شكلُ الخطأ

كلُّ خطأٍ يأتي بهذا الشكل بالضبط — فاقرأ error.code ولا تُحلّل النصّ.

{
  "error": {
    "code":       "quota_exceeded",   // اقرأ هذا
    "message":    "تجاوزتَ حصّةَ المدّة.",
    "message_en": "Subscription period quota exceeded.",
    "doc_url":    "https://nafarat.app/developers/errors#quota_exceeded",
    "request_id": "req_8f3a…"    // اذكره في أيّ بلاغ
  }
}

«لا مسار» ليس خطأً. حين لا نجد مساراً بين نقطتين يعود 200 ومعه "status": "no_route_found" ومصفوفةُ plans فارغة — لأنه جوابٌ حُسب لا عطلٌ وقع، وتغطيتُنا معلَنةٌ سلفاً. ولو جعلناه خطأً لأفسد كلَّ لوحةِ مراقبةٍ عندك. وهو يُحتسب من حصّتك لأننا حسبناه.

المصادقة HTTP 401

missing_key

هذا المسار يتطلّب مفتاحَ وصول.

This endpoint requires an access key.

العلاج

أرسِل المفتاحَ في ترويسة Authorization: Bearer nfr_live_… — أو X-Nafarat-Key. وتحقّق أن وكيلك (proxy) لا يحذف ترويسةَ المصادقة.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

invalid_key

مفتاحُ الوصول غيرُ صالح.

The supplied access key is not valid.

العلاج

المفتاحُ لا يطابق أيَّ مفتاحٍ عندنا. تحقّق من نسخه كاملاً بلا فراغاتٍ ولا سطرٍ جديد، ومن أنك لا تخلط مفتاحَ test بمفتاح live.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

revoked_key

مفتاحُ الوصول مُلغى.

This access key has been revoked.

العلاج

هذا المفتاحُ أُلغي — منك أو منّا. ولّد غيرَه من لوحتك؛ والإلغاءُ يسري فوراً بلا انتظار.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

الاشتراك HTTP 402

subscription_inactive

الاشتراكُ منتهٍ وانقضت مهلةُ السماح.

Your subscription has expired and the grace period has ended.

العلاج

انتهت مدّةُ اشتراكك وانقضت مهلةُ السماح. جدّد من لوحتك. ⚠️ ولا تجديدَ تلقائيّاً عندنا — الدفعُ فعلٌ تقوم به، ونذكّرك قبل الانتهاء بسبعةِ أيّامٍ وثلاثةٍ ويوم.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

النطاق HTTP 403

scope_out_of_range

أحدُ طرفَي الطلب خارجَ النطاق المشتَرك.

One endpoint of the request lies outside your subscribed scope.

العلاج

أحدُ طرفَي الطلب خارجَ المحافظات المشمولة باشتراكك. الردُّ يذكر point (أيُّ الطرفين) وpoint_governorate (أينَ يقع فعلاً) وsubscribed_governorates. وسّع نطاقَك أو صحّح النقطة.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

غيرُ موجود HTTP 404

route_not_found

لا خطَّ بهذا المعرّف في المحافظات المفعَّلة.

No such route in the active governorates.

العلاج

لا خطَّ بهذا المعرّف في بيانات المحافظات المفعَّلة الآن — ربما حُذف أو دُمج مع غيره عند تحديث الشبكة. خذ المعرّفاتِ الحاليّة من GET /v1/routes، وأبطِل كاشَك حين يتغيّر X-Nafarat-Data-Version. وهذا الخطأ لا يُحتسب من حصّتك.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

صياغةُ الطلب HTTP 422

invalid_request

الطلبُ غيرُ صالحِ الصياغة.

The request is malformed.

العلاج

صياغةُ الطلب غيرُ صالحة. الردُّ يحمل fields وفيه اسمُ كلّ حقلٍ مرفوضٍ وسببُه. وهذا الخطأ لا يُحتسب من حصّتك.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

الحدود HTTP 429

rate_limit_exceeded

تجاوزتَ السقفَ اللحظيّ للنداءات.

Per-second rate limit exceeded.

العلاج

تجاوزتَ عددَ النداءات المسموحِ في الثانية. الردُّ يحمل Retry-After — انتظرها ثمّ أعِد. وفي الإنتاج: طابورٌ عندك بمعدّلٍ ثابتٍ أفضلُ من إعادةٍ فوريّة.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

quota_exceeded

تجاوزتَ حصّةَ المدّة.

Subscription period quota exceeded.

العلاج

استُهلكت حصّةُ المدّة كاملةً. راقب X-Quota-Remaining في كلّ ردٍّ لتعرف قبل أن تصطدم، وX-Quota-Reset يذكر لحظةَ التصفير — وهي نهايةُ مدّة اشتراكك لا أوّلُ الشهر الميلاديّ.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

platform_busy

الواجهةُ مشغولةٌ لحظياً — أعِد المحاولة.

The platform is momentarily saturated; please retry.

العلاج

الواجهةُ بلغت سقفَها الكلّيَّ لحظياً (سقفٌ نحمي به خدمةَ الركّاب). أعِد بعد الثانية التي تذكرها Retry-After. وتكرارُه يعني أن تتواصل معنا.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

من عندنا HTTP 500

engine_error

تعذّر حسابُ المسار.

The routing engine failed to compute a result.

العلاج

خطأٌ من عندنا. أعِد المحاولة، وإن تكرّر فأرسل لنا request_id من الردّ — به نجد طلبَك بعينه في سجلّاتنا. وهذا الخطأ لا يُحتسب من حصّتك.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

التوقّف HTTP 503

platform_disabled

الواجهةُ التجاريّةُ متوقّفةٌ مؤقّتاً.

The commercial API is temporarily disabled.

العلاج

الواجهةُ التجاريّةُ متوقّفةٌ مؤقّتاً بقرارِ تشغيل. راجع صفحةَ الجهوزيّة.

ما زال يحدث؟ افتح طلبَ دعمٍ بهذا الرمز

ما يُحتسب من حصّتك وما لا يُحتسب

الحالة	يُحتسب؟	لماذا
200 مسارٌ وُجد	نعم	خدمةٌ أُدّيت
200 `no_route_found`	نعم	جوابٌ حُسب، والتغطيةُ معلَنةٌ سلفاً
4xx طلبٌ خاطئُ الصياغة	لا	لم نحسب شيئاً
403 خارجَ النطاق	لا	رُفض قبل المحرّك
429 تجاوزُ حدّ	لا	لم يُنفَّذ الطلب
5xx خطأٌ من عندنا	لا	عطلُنا لا يُفوتَر عليك