البدء
الأخطاء ورموز الحالة
رموز حالة HTTP، وأشكال استجابات الأخطاء، وغلاف توفّر المحرّك.
الأخطاء ورموز الحالة
تستخدم Navvo رموز حالة HTTP التقليدية وجسم خطأ متّسقًا.
رموز الحالة
| الرمز | المعنى |
|---|---|
200 OK | GET ناجح. |
201 Created | POST ناجح (يعيد NestJS الرمز 201 لمعالِجات POST، حتى عندما لا يُحفَظ شيء — مثل التوجيه). |
400 Bad Request | معاملات/جسم غير صالح أو مفقود (فشل التحقّق). |
401 Unauthorized | مفتاح API مفقود أو غير معروف. |
403 Forbidden | المفتاح ملغى، أو يفتقد النطاق المطلوب، أو تم تجاوز حدّ معدّل. |
404 Not Found | المسار غير موجود. (ملاحظة: بعض عمليات البحث تعيد 200 مع جسم null بدلًا من ذلك — راجع أدناه.) |
502 / 503 | إحدى تبعيات Navvo (البلاطات، الصور) غير متوفّرة. |
جسم الخطأ
تستخدم الأخطاء شكل استثناء NestJS القياسي:
{
"statusCode": 403,
"message": "API key missing required scopes: routing",
"error": "Forbidden"
}
قد تعيد أخطاء التحقّق (400) الحقل message على هيئة مصفوفة من الرسائل على مستوى الحقول:
{
"statusCode": 400,
"message": ["email must be an email", "password must be longer than or equal to 10 characters"],
"error": "Bad Request"
}
سلوكان يجدر معرفتهما
1. غلاف "available" (نقاط نهاية المحرّك)
نقاط النهاية المدعومة بمحرّك Navvo — الترميز الجغرافي، والتوجيه، وأجزاء من حركة المرور — لا تعيد خطأ 5xx عندما يتعذّر الوصول إلى المحرّك. بل تعيد بدلًا من ذلك 200/201 طبيعية مع راية available: false (أو ok: false) وتُعيد إليك طلبك:
{
"provider": "navvo",
"available": false,
"path": "route",
"request": { "locations": [ { "lat": 31.95, "lon": 35.91 } ], "costing": "auto" }
}
تحقّق دائمًا من القيمة المنطقية
available / ok في استجابات المحرّك قبل قراءة data. لا يضمن الرمز 200 نتيجة قابلة للاستخدام.2. "غير موجود" قد تكون 200 null
تعيد بعض نقاط نهاية البحث (وأبرزها GET /places/{slug}) HTTP 200 مع جسم null عندما لا يكون المورد موجودًا، بدلًا من 404. عامِل الجسم الفارغ/null على أنه "غير موجود".
معالجة الأخطاء
const res = await fetch("https://navvo.io/api/v1/search?q=cafe", {
headers: { "x-api-key": key },
});
if (res.status === 401 || res.status === 403) {
// Auth/scope/quota problem — inspect message, don't retry blindly.
const err = await res.json();
throw new Error(`${err.statusCode}: ${err.message}`);
}
if (!res.ok) {
// 400/5xx
throw new Error(`Request failed: ${res.status}`);
}
const data = await res.json();