البدء
الأخطاء ورموز الحالة
رموز حالة HTTP، وأشكال استجابات الأخطاء، وغلاف توفّر المحرّك.
الأخطاء ورموز الحالة
تستخدم Navvo رموز حالة HTTP التقليدية وجسم خطأ متّسقًا.
رموز الحالة
| الرمز | المعنى |
|---|---|
200 OK | GET ناجح. |
201 Created | POST ناجح (يعيد NestJS الرمز 201 لمعالِجات POST، حتى عندما لا يُحفَظ شيء — مثل التوجيه). |
400 Bad Request | معاملات/جسم غير صالح أو مفقود (فشل التحقّق). |
401 Unauthorized | مفتاح API مفقود أو غير معروف. |
403 Forbidden (الوصول) | المفتاح معطَّل (API key revoked) أو يفتقد النطاق المطلوب (code بقيمة FORBIDDEN)، أو يُستخدم من موقع أو عنوان IP غير مسموح به (code بقيمة KEY_WEBSITE_NOT_ALLOWED أو KEY_IP_NOT_ALLOWED، راجع تقييد المفتاح). إعادة المحاولة لن تفيد: أصلِح المفتاح. |
403 Forbidden (الحصّة) | تجاوز المفتاح حصّته في الدقيقة أو في اليوم، أو الحدّ لكل عنوان IP (code بقيمة QUOTA_EXCEEDED). ويذكر details قيم limit وwindow وobserved، ولنافذة الدقيقة retryAfterSeconds التي تُرسَل أيضًا في Retry-After. راجع حدود المعدّل. |
404 Not Found | المسار غير موجود. (ملاحظة: بعض عمليات البحث تعيد 200 مع جسم null بدلًا من ذلك — راجع أدناه.) |
429 Too Many Requests | أرسل عنوان IP الخاص بك طلبات كثيرة جدًّا إلى نقطة نهاية واحدة (code بقيمة RATE_LIMITED). انتظر الثواني المذكورة في ترويسة Retry-After ثم أعد المحاولة. |
502 / 503 | إحدى تبعيات Navvo (البلاطات، الصور) غير متوفّرة. |
لا يتلقّى المفتاح غير المحدود الرمز QUOTA_EXCEEDED أبدًا.
جسم الخطأ
تستخدم الأخطاء شكل استثناء 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 === 429) {
// Throttled — wait for Retry-After (seconds) before sending to this endpoint again.
const waitSeconds = Number(res.headers.get("retry-after")) || 1;
throw new Error(`Rate limited; retry in ${waitSeconds}s`);
}
if (res.status === 401 || res.status === 403) {
// Auth/scope/quota problem — branch on err.code (e.g. QUOTA_EXCEEDED), don't retry blindly.
const err = await res.json();
throw new Error(`${err.statusCode} ${err.code}: ${err.message}`);
}
if (!res.ok) {
// 400/5xx
throw new Error(`Request failed: ${res.status}`);
}
const data = await res.json();