إنتقل إلى المحتوى الرئيسي

الأخطاء

الطلب المرفوض يُجاب بحالة HTTP ومشكلة بصيغة RFC 9457 ‏(Content-Type: application/problem+json). تفرّع على الحالة أولًا ثم على code. لا تحلّل title ولا detail: هما للبشر.

من الخدمة​

تأتي أغلب الأخطاء من الخدمة التي خلف العملية:

{
"type": "https://errors.zaitrack.app/ZTK74001",
"title": "Not Found",
"status": 404,
"code": "ZTK74001",
"detail": "not found"
}
  • code هو ZTK وأرقام. لكل خدمة نطاق خاص بها، ويحتفظ الرمز بمعناه بعد نشره.
  • detail يذكر الخطأ، مثل vehicleId (required) and driverId must be UUIDs. بعض الخدمات تضع الرسالة في title ولا ترسل detail.
الحالةمعناها
400الجسم أو أحد المعاملات غير صالح: صحّح الطلب.
401لم تمرّر البوابة إلى الخدمة أي مؤسسة (خلل في البوابة أو الإعداد: أبلغ عنه).
404لا يوجد هذا المورد في مؤسستك. ومورد مؤسسة أخرى 404 أيضًا.
409حالة المورد تمنع الإجراء (جهاز مرتبط من قبل، مهمة موزّعة من قبل).
412يذكر If-Match إصدارًا لم يعد الحالي: اقرأ مجددًا.
422يذكر الجسم شيئًا غير موجود أو ليس لك (معرّف جهاز أو سائق).
500خلل من جهتنا: أعد المحاولة لاحقًا وأبلغ عن X-Zaitrack-Request-Id.

من البوابة​

تجيب البوابة قبل الخدمة حين يكون الخطأ في بيانات الاعتماد أو النطاق أو مفتاح منع التكرار أو المنطقة. مشكلاتها لها type تحت https://api.zaitrack.app/errors/ وcode منقوط وrequest_id:

{
"type": "https://api.zaitrack.app/errors/scope-missing",
"title": "Required scope missing",
"status": 403,
"code": "auth.token.scope_missing",
"detail": "Missing scopes: vehicles:write",
"request_id": "…"
}
الحالةcodeمعناها
401auth.api_key.invalidالمفتاح مشوّه أو مجهول أو مُبطل أو منتهٍ.
403auth.api_key.ip_not_allowedللمفتاح قائمة عناوين مسموح بها وعنوانك ليس فيها.
403auth.tenant_missingبيانات الاعتماد غير مرتبطة بمؤسسة.
403auth.token.scope_missingينقص بيانات الاعتماد نطاق العملية؛ ويذكره detail.
403step_up_requiredتحتاج العملية إلى تحقق MFA حديث (أوامر الأجهزة).
400idempotency.requiredتحتاج العملية إلى Idempotency-Key.
409idempotency.body_mismatchاستُخدم المفتاح من قبل بجسم مختلف.
409idempotency.in_flightطلب بهذا المفتاح ما زال قيد التنفيذ.
421misdirected_requestمؤسستك في منطقة أخرى: اتبع Location. راجع المناطق.
503auth.api_key.unavailable، idempotency.unavailableإحدى تبعيات البوابة متوقفة: أعد المحاولة بتأخير متزايد.

ردّان ليسا مشكلات:

  • رمز وصول OAuth غير صالح أو منتهٍ يتلقى 401 مع ترويسة WWW-Authenticate: Bearer.
  • الطلب الذي يتجاوز حدّ المعدّل يتلقى 429 مع {"error_msg": "rate limit exceeded"}. راجع حدود المعدّل.